Provided by: manpages-pl-dev_4.23.1-1_all 
NAZWA
malloc, free, calloc, realloc, reallocarray - przydziela i zwalnia pamięć dynamiczną
BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)
SKŁADNIA
#include <stdlib.h>
void *malloc(size_t size);
void free(void *_Nullable ptr);
void *calloc(size_t nmemb, size_t size);
void *realloc(void *_Nullable ptr, size_t size);
void *reallocarray(void *_Nullable ptr, size_t nmemb, size_t size);
Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):
reallocarray():
Od glibc 2.29:
_DEFAULT_SOURCE
glibc 2.28 i wcześniejsze:
_GNU_SOURCE
OPIS
malloc()
Funkcja malloc() przydziela pamięć o rozmiarze size bajtów i zwraca wskaźnik do
przydzielonej pamięci. Pamięć nie jest inicjowana. Jeśli size wynosi 0, to malloc() zwraca
unikatową wartość wskaźnika, który potem można z powodzeniem przekazać do free() (zob.
„Nieprzenośne zachowanie”).
free()
Funkcja free() zwalnia obszar pamięci wskazywany przez ptr, który został wcześniej
przydzielony za pomocą wywołania malloc() lub funkcji powiązanych. W przeciwnym przypadku
lub gdy ptr zostało już uwolnione, funkcja zachowa się w sposób nieokreślony. Jeśli ptr
jest równe NULL, nie zostanie wykonana żadna operacja.
calloc()
Funkcja calloc() przydziela pamięć dla tablicy o liczbie nmemb elementów o rozmiarze size
bajtów każdy i zwraca wskaźnik do przydzielonej pamięci. Pamięć jest ustawiana na zero.
Jeśli nmemb lub size wynosi 0, to calloc() zwraca unikatową wartość wskaźnika, którą potem
można z powodzeniem przekazać do free().
Jeśli przemnożenie nmemb i size spowodowałoby przepełnienie liczby całkowitej, calloc()
zwróci błąd. Przepełnienie nie zostałoby natomiast wykryte w następującym wywołaniu do
malloc(), które spowodowałoby przydzielenie bloku pamięci o nieprawidłowym rozmiarze:
malloc(nmemb * size);
realloc()
Funkcja realloc() zmienia rozmiar bloku pamięci wskazywanego przez ptr na size 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ęć
nie zostanie zainicjowana.
Jeśli ptr jest równe NULL, to wywołanie jest równoważne malloc(size) dla wszystkich
wartości size.
jeśli size jest równe zeru i ptr jest różny od NULL, to wywołanie jest równoważne z
free(ptr) (lecz zob. „Nieprzenośne zachowanie” w sprawie problemów z przenośnością).
Jeżeli ptr jest różne od NULL, to musi on pochodzić z wcześniejszego wywołania malloc()
lub powiązanych funkcji. Jeśli wskazywany obszar został przemieszczony, to wykonywane jest
free(ptr).
reallocarray()
Funkcja reallocarray() zmieni rozmiar (i ewentualnie przesunie) blok pamięci, na który
wskazuje ptr, do wielkości odpowiednio dużej dla tablicy nmemb elementów, każdy z których
ma rozmiar size bajtów. Jest to równoważne wywołaniu
realloc(ptr, nmemb * size);
Jednak w odróżnieniu od tego wywołania realloc(), reallocarray() bezpiecznie zawiedzie w
przypadku, w którym mnożenie prowadziłoby do przepełnienia. Jeśli takie przepełnienie
wystąpi, reallocarray() zwróci błąd.
WARTOŚĆ ZWRACANA
Funkcje malloc(), calloc(), realloc() i reallocarray() 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ą errno. Próba
przydzielenia więcej niż PTRDIFF_MAX bajtów jest uważana za błąd, ponieważ tak duże
obiekty mogą później spowodować przepełnienie przy odjęciu wskaźnika.
Funkcja free() nie zwraca żadnej wartości i zachowuje errno.
Funkcje realloc() i reallocarray() zwracają NULL jeśli ptr nie wynosi NULL, a żądany
rozmiar wynosi zero; nie jest to uważane za błąd (problemy z przenośnością opisano w
rozdziale „Nieprzenośne zachowanie”). W innym przypadku, żądany wskaźnik może być taki sam
jak ptr, jeśli alokacja nie została przesunięta (np. było miejsce na poszerzenie alokacji
w miejscu) lub inny od ptr, jeśli alokację przeniesiono pod nowy adres. Jeśli funkcje te
zawiodą, pierwotny blok pozostaje nienaruszony; nie jest zwalniany ani przesuwany.
BŁĘDY
calloc(), malloc(), realloc() i reallocarray() mogą zawieść z następującym błędem:
ENOMEM Brak wolnej pamięci. Prawdopodobnie aplikację dotknął limit RLIMIT_AS lub
RLIMIT_DATA opisany w getrlimit(2). Innym powodem, może być przekroczenie liczby
mapowań określonej w /proc/sys/vm/max_map_count przez proces wywołujący.
ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku
attributes(7).
┌────────────────────────────────────────────────┬────────────────────────┬───────────────┐
│Interfejs │ Atrybut │ Wartość │
├────────────────────────────────────────────────┼────────────────────────┼───────────────┤
│malloc(), free(), calloc(), realloc() │ Bezpieczeństwo wątkowe │ MT-bezpieczne │
└────────────────────────────────────────────────┴────────────────────────┴───────────────┘
STANDARDY
malloc()
free()
calloc()
realloc()
C11, POSIX.1-2008.
reallocarray()
Brak.
HISTORIA
malloc()
free()
calloc()
realloc()
POSIX.1-2001, C89.
reallocarray()
glibc 2.26. OpenBSD 5.6, FreeBSD 11.0.
Od glibc 2.30, malloc() i powiązane funkcje odmówią rozmiarów większych od PTRDIFF_MAX.
free() zachowuje errno zaczynając od glibc 2.33.
UWAGI
Linux stosuje optymistyczną strategię przydzielania pamięci. Oznacza to, że gdy malloc()
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
/proc/sys/vm/overcommit_memory i /proc/sys/vm/oom_adj w proc(5) oraz plik
Documentation/vm/overcommit-accounting.rst w źródłach jądra Linuksa.
Zwykle malloc() przydziela pamięć ze sterty i ustawia wymagany rozmiar sterty, używając
sbrk(2). Podczas przydzielania bloków pamięci większych niż MMAP_THRESHOLD bajtów,
implementacja malloc() w glibc używa prywatnych anonimowych map z mmap(2). MMAP_THRESHOLD
domyślnie wynosi 128 kB, ale można to zmienić za pomocą mallopt(3). Przed Linuksem 4.7,
limit zasobów RLIMIT_DATA (patrz getrlimit(2)) nie miał zastosowania do pamięci
przydzielonej przy użyciu mmap(2); od Linuksa 4.7 limit ten stosuje się również dla
alokacji dokonywanych za pomocą mmap(2).
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 areny przydziału pamięci,
jeśli wykryte zostanie oczekiwanie na mutex. Każda arena jest dużym regionem pamięci
wewnętrznie zaalokowanym przez system (za pomocą brk(2) lub mmap(2)) i jest zarządzana
przy użyciu jej własnych muteksów.
Jeśli dany program używa prywatnego alokatora pamięci, powinien to czynić przez
zastąpienie malloc(), free(), calloc() i realloc(). Funkcje zastępujące muszą
implementować opisywane zachowania glibc, w tym obsługę errno, 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 free() nie będzie
zachowywać errno, to pozornie niepowiązane funkcje biblioteczne mogą zawodzić bez
prawidłowej przyczyny w errno. Prywatne alokatory pamięci mogą spowodować konieczność
zastąpienia również innych funkcji glibc; więcej szczegółów w rozdziale „Replacing malloc”
w podręczniku glibc.
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.
Implementację malloc() można dostosowywać za pomocą zmiennych środowiskowych. Szczegóły
opisano w mallopt(3).
Nieprzenośne zachowanie
Zachowanie tych funkcji, gdy żądany rozmiar wynosi zero, zależy od glibc; inne
implementacje mogą zwrócić NULL bez ustawienia errno, a przenośne programy POSIX powinny
tolerować takie zachowanie. Zob. realloc(3p).
POSIX wymaga ustawiania errno 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.
Przenośne programy nie powinny używać prywatnych alokatorów pamięci, ponieważ POSIX i
standard C nie dopuszczają zastępowania malloc(), free(), calloc() i realloc().
PRZYKŁADY
#include <err.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#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);
}
ZOBACZ TAKŻE
valgrind(1), brk(2), mmap(2), alloca(3), malloc_get_state(3), malloc_info(3),
malloc_trim(3), malloc_usable_size(3), mallopt(3), mcheck(3), mtrace(3), posix_memalign(3)
Szczegóły na temat implementacji biblioteki GNU C są dostępne pod adresem
⟨https://sourceware.org/glibc/wiki/MallocInternals⟩.
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz
<ankry@green.mf.pg.gda.pl>, Robert Luberda <robert@debian.org> i Michał Kułach
<michal.kulach@gmail.com>
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji
można uzyskać zapoznając się z GNU General Public License w wersji 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ lub nowszej. Nie przyjmuje się ŻADNEJ
ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej
⟨manpages-pl-list@lists.sourceforge.net⟩.