.\" -*- coding: UTF-8 -*-
'\" t
.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
.\" and Copyright 2007, 2012, 2018, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" 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 <stdlib.h>\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 <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);
}
.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
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>
.
.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 .
