.\" -*- coding: UTF-8 -*- '\" t .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) .\" and Copyright 2007, 2012, 2018, Michael Kerrisk .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) .\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 .\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) .\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). .\" .\" FIXME . Review http://austingroupbugs.net/view.php?id=374 .\" to see what changes are required on this page. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH malloc 3 "2 maja 2024 r." "Linux man\-pages 6.9.1" .SH NAZWA malloc, free, calloc, realloc, reallocarray \- przydziela i zwalnia pamięć dynamiczną .SH BIBLIOTEKA Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP) .SH SKŁADNIA .nf \fB#include \fP .P \fBvoid *malloc(size_t \fP\fIsize\fP\fB);\fP \fBvoid free(void *_Nullable \fP\fIptr\fP\fB);\fP \fBvoid *calloc(size_t \fP\fInmemb\fP\fB, size_t \fP\fIsize\fP\fB);\fP \fBvoid *realloc(void *_Nullable \fP\fIptr\fP\fB, size_t \fP\fIsize\fP\fB);\fP \fBvoid *reallocarray(void *_Nullable \fP\fIptr\fP\fB, size_t \fP\fInmemb\fP\fB, size_t \fP\fIsize\fP\fB);\fP .fi .P .RS -4 Wymagane ustawienia makr biblioteki glibc (patrz \fBfeature_test_macros\fP(7)): .RE .P \fBreallocarray\fP(): .nf Od glibc 2.29: _DEFAULT_SOURCE glibc 2.28 i wcześniejsze: _GNU_SOURCE .fi .SH OPIS .SS malloc() Funkcja \fBmalloc\fP() przydziela pamięć o rozmiarze \fIsize\fP bajtów i zwraca wskaźnik do przydzielonej pamięci. \fIPamięć nie jest inicjowana\fP. Jeśli \fIsize\fP wynosi 0, to \fBmalloc\fP() zwraca unikatową wartość wskaźnika, który potem można z powodzeniem przekazać do \fBfree\fP() (zob. \[Bq]Nieprzenośne zachowanie\[rq]). .SS free() Funkcja \fBfree\fP() zwalnia obszar pamięci wskazywany przez \fIptr\fP, który został wcześniej przydzielony za pomocą wywołania \fBmalloc\fP() lub funkcji powiązanych. W przeciwnym przypadku lub gdy \fIptr\fP zostało już uwolnione, funkcja zachowa się w sposób nieokreślony. Jeśli \fIptr\fP jest równe NULL, nie zostanie wykonana żadna operacja. .SS calloc() Funkcja \fBcalloc\fP() przydziela pamięć dla tablicy o liczbie \fInmemb\fP elementów o rozmiarze \fIsize\fP bajtów każdy i zwraca wskaźnik do przydzielonej pamięci. Pamięć jest ustawiana na zero. Jeśli \fInmemb\fP lub \fIsize\fP wynosi 0, to \fBcalloc\fP() zwraca unikatową wartość wskaźnika, którą potem można z powodzeniem przekazać do \fBfree\fP(). .P Jeśli przemnożenie \fInmemb\fP i \fIsize\fP spowodowałoby przepełnienie liczby całkowitej, \fIcalloc\fP() zwróci błąd. Przepełnienie nie zostałoby natomiast wykryte w następującym wywołaniu do \fBmalloc\fP(), które spowodowałoby przydzielenie bloku pamięci o nieprawidłowym rozmiarze: .P .in +4n .EX malloc(nmemb * size); .EE .in .SS realloc() Funkcja \fBrealloc\fP() zmienia rozmiar bloku pamięci wskazywanego przez \fIptr\fP na \fIsize\fP bajtów. Zawartość pamięci nie zostanie zmieniona w zakresie od początku obszaru do minimum ze starego i nowego rozmiaru. Jeśli nowy rozmiar jest większy od starego, to dodana pamięć \fInie\fP zostanie zainicjowana. .P Jeśli \fIptr\fP jest równe NULL, to wywołanie jest równoważne \fImalloc(size)\fP dla wszystkich wartości \fIsize\fP. .P jeśli \fIsize\fP jest równe zeru i \fIptr\fP jest różny od NULL, to wywołanie jest równoważne z \fIfree(ptr)\fP (lecz zob. \[Bq]Nieprzenośne zachowanie\[rq] w sprawie problemów z przenośnością). .P Jeżeli \fIptr\fP jest różne od NULL, to musi on pochodzić z wcześniejszego wywołania \fBmalloc\fP() lub powiązanych funkcji. Jeśli wskazywany obszar został przemieszczony, to wykonywane jest \fIfree(ptr)\fP. .SS reallocarray() Funkcja \fBreallocarray\fP() zmieni rozmiar (i ewentualnie przesunie) blok pamięci, na który wskazuje \fIptr\fP, do wielkości odpowiednio dużej dla tablicy \fInmemb\fP elementów, każdy z których ma rozmiar \fIsize\fP bajtów. Jest to równoważne wywołaniu .P .in +4n .EX realloc(ptr, nmemb * size); .EE .in .P Jednak w odróżnieniu od tego wywołania \fBrealloc\fP(), \fBreallocarray\fP() bezpiecznie zawiedzie w przypadku, w którym mnożenie prowadziłoby do przepełnienia. Jeśli takie przepełnienie wystąpi, \fBreallocarray\fP() zwróci błąd. .SH "WARTOŚĆ ZWRACANA" Funkcje \fBmalloc\fP(), \fBcalloc\fP(), \fBrealloc\fP() i \fBreallocarray\fP() zwracają wskaźnik do przydzielonej pamięci, który jest odpowiednio wyrównany dla dowolnego typu, który mieści się w żądanym lub mniejszym rozmiarze. W razie błędu funkcje te zwracają NULL i ustawiają \fIerrno\fP. Próba przydzielenia więcej niż \fBPTRDIFF_MAX\fP bajtów jest uważana za błąd, ponieważ tak duże obiekty mogą później spowodować przepełnienie przy odjęciu wskaźnika. .P Funkcja \fBfree\fP() nie zwraca żadnej wartości i zachowuje \fIerrno\fP. .P Funkcje \fBrealloc\fP() i \fBreallocarray\fP() zwracają NULL jeśli \fIptr\fP nie wynosi NULL, a żądany rozmiar wynosi zero; nie jest to uważane za błąd (problemy z przenośnością opisano w rozdziale \[Bq]Nieprzenośne zachowanie\[rq]). W innym przypadku, żądany wskaźnik może być taki sam jak \fIptr\fP, jeśli alokacja nie została przesunięta (np. było miejsce na poszerzenie alokacji w miejscu) lub inny od \fIptr\fP, jeśli alokację przeniesiono pod nowy adres. Jeśli funkcje te zawiodą, pierwotny blok pozostaje nienaruszony; nie jest zwalniany ani przesuwany. .SH BŁĘDY \fBcalloc\fP(), \fBmalloc\fP(), \fBrealloc\fP() i \fBreallocarray\fP() mogą zawieść z następującym błędem: .TP \fBENOMEM\fP Brak wolnej pamięci. Prawdopodobnie aplikację dotknął limit \fBRLIMIT_AS\fP lub \fBRLIMIT_DATA\fP opisany w \fBgetrlimit\fP(2). Innym powodem, może być przekroczenie liczby mapowań określonej w \fI/proc/sys/vm/max_map_count\fP przez proces wywołujący. .SH ATRYBUTY Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. Interfejs Atrybut Wartość T{ .na .nh \fBmalloc\fP(), \fBfree\fP(), \fBcalloc\fP(), \fBrealloc\fP() T} Bezpieczeństwo wątkowe MT\-bezpieczne .TE .SH STANDARDY .TP \fBmalloc\fP() .TQ \fBfree\fP() .TQ \fBcalloc\fP() .TQ \fBrealloc\fP() C11, POSIX.1\-2008. .TP \fBreallocarray\fP() Brak. .SH HISTORIA .TP \fBmalloc\fP() .TQ \fBfree\fP() .TQ \fBcalloc\fP() .TQ \fBrealloc\fP() POSIX.1\-2001, C89. .TP \fBreallocarray\fP() glibc 2.26. OpenBSD 5.6, FreeBSD 11.0. .P Od glibc 2.30, \fBmalloc\fP() i powiązane funkcje odmówią rozmiarów większych od \fBPTRDIFF_MAX\fP. .P \fBfree\fP() zachowuje \fIerrno\fP zaczynając od glibc 2.33. .SH UWAGI Linux stosuje optymistyczną strategię przydzielania pamięci. Oznacza to, że gdy \fBmalloc\fP() zwraca wartość różną od NULL, nie ma gwarancji, iż pamięć faktycznie jest dostępna. Jeśli okaże się, że systemowi brakło pamięci, niesławny zabójca OOM ("out\-of\-memory killer") zabije jeden lub więcej procesów. Więcej informacji zawiera opis plików \fI/proc/sys/vm/overcommit_memory\fP i \fI/proc/sys/vm/oom_adj\fP w \fBproc\fP(5) oraz plik \fIDocumentation/vm/overcommit\-accounting.rst\fP w źródłach jądra Linuksa. .P Zwykle \fBmalloc\fP() przydziela pamięć ze sterty i ustawia wymagany rozmiar sterty, używając \fBsbrk\fP(2). Podczas przydzielania bloków pamięci większych niż \fBMMAP_THRESHOLD\fP bajtów, implementacja \fBmalloc\fP() w glibc używa prywatnych anonimowych map z \fBmmap\fP(2). \fBMMAP_THRESHOLD\fP domyślnie wynosi 128\ kB, ale można to zmienić za pomocą \fBmallopt\fP(3). Przed Linuksem 4.7, limit zasobów \fBRLIMIT_DATA\fP (patrz \fBgetrlimit\fP(2)) nie miał zastosowania do pamięci przydzielonej przy użyciu \fBmmap\fP(2); od Linuksa 4.7 limit ten stosuje się również dla alokacji dokonywanych za pomocą \fBmmap\fP(2). .P Aby uniknąć uszkodzenia pamięci w aplikacjach wielowątkowych, funkcje te wewnętrznie stosują muteksy, chroniące struktury danych odnoszące się do zarządzania pamięcią. W aplikacji wielowątkowej, w której wątki jednocześnie przydzielają i zwalniają pamięć mogą występować oczekiwania na dostęp do muteksów. Aby przydział pamięci w aplikacji wielowątkowej był skalowalny, biblioteka glibc tworzy dodatkowe \fIareny przydziału pamięci\fP, jeśli wykryte zostanie oczekiwanie na mutex. Każda arena jest dużym regionem pamięci wewnętrznie zaalokowanym przez system (za pomocą \fBbrk\fP(2) lub \fBmmap\fP(2)) i jest zarządzana przy użyciu jej własnych muteksów. .P Jeśli dany program używa prywatnego alokatora pamięci, powinien to czynić przez zastąpienie \fBmalloc\fP(), \fBfree\fP(), \fBcalloc\fP() i \fBrealloc\fP(). Funkcje zastępujące muszą implementować opisywane zachowania glibc, w tym obsługę \fIerrno\fP, alokację o zerowym rozmiarze i sprawdzanie przepełnienia; w innym przypadku inne funkcje biblioteczne mogą się załamać lub działać niepoprawnie. Na przykład, jeśli zastępcze \fIfree\fP() nie będzie zachowywać \fIerrno\fP, to pozornie niepowiązane funkcje biblioteczne mogą zawodzić bez prawidłowej przyczyny w \fIerrno\fP. Prywatne alokatory pamięci mogą spowodować konieczność zastąpienia również innych funkcji glibc; więcej szczegółów w rozdziale \[Bq]Replacing malloc\[rq] w podręczniku glibc. .P Załamania w alokatorach pamięci są niemal zawsze związane z uszkodzeniami sterty, takimi jak przekroczenie rozmiaru przydzielonego fragmentu lub dwukrotne zwolnienie tego samego wskaźnika. .P Implementację \fBmalloc\fP() można dostosowywać za pomocą zmiennych środowiskowych. Szczegóły opisano w \fBmallopt\fP(3). .SS "Nieprzenośne zachowanie" Zachowanie tych funkcji, gdy żądany rozmiar wynosi zero, zależy od glibc; inne implementacje mogą zwrócić NULL bez ustawienia \fIerrno\fP, a przenośne programy POSIX powinny tolerować takie zachowanie. Zob. \fBrealloc\fP(3p). .P POSIX wymaga ustawiania \fIerrno\fP przez alokatory pamięci, przy niepowodzeniu. Jednak standard C tego nie wymaga, dlatego aplikacje przenośne na platformy poza POSIX nie powinny zakładać takiego zachowania. .P Przenośne programy nie powinny używać prywatnych alokatorów pamięci, ponieważ POSIX i standard C nie dopuszczają zastępowania \fBmalloc\fP(), \fBfree\fP(), \fBcalloc\fP() i \fBrealloc\fP(). .SH PRZYKŁADY .EX #include #include #include #include #include \& #define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type))) #define MALLOC(type) MALLOCARRAY(1, type) \& static inline void *my_mallocarray(size_t nmemb, size_t size); \& int main(void) { char *p; \& p = MALLOCARRAY(32, char); if (p == NULL) err(EXIT_FAILURE, "malloc"); \& strlcpy(p, "foo", 32); puts(p); } \& static inline void * my_mallocarray(size_t nmemb, size_t size) { return reallocarray(NULL, nmemb, size); } .EE .SH "ZOBACZ TAKŻE" .\" http://g.oswego.edu/dl/html/malloc.html .\" A Memory Allocator - by Doug Lea .\" .\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html .\" Linux Heap, Contention in free() - David Boreham .\" .\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html .\" malloc() Performance in a Multithreaded Linux Environment - .\" Check Lever, David Boreham .\" .ad l .nh \fBvalgrind\fP(1), \fBbrk\fP(2), \fBmmap\fP(2), \fBalloca\fP(3), \fBmalloc_get_state\fP(3), \fBmalloc_info\fP(3), \fBmalloc_trim\fP(3), \fBmalloc_usable_size\fP(3), \fBmallopt\fP(3), \fBmcheck\fP(3), \fBmtrace\fP(3), \fBposix_memalign\fP(3) .P Szczegóły na temat implementacji biblioteki GNU C są dostępne pod adresem .UR https://sourceware.org/glibc/wiki/MallocInternals .UE . .PP .SH TŁUMACZENIE Tłumaczenie niniejszej strony podręcznika: Andrzej Krzysztofowicz , Robert Luberda i Michał Kułach . .PP Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License w wersji 3 .UE lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI. .PP Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej .MT manpages-pl-list@lists.sourceforge.net .ME .