リナックスコマンド

mallocのヘルプ・マニュアル

日本語 英語

• help
• man

malloc --help

man malloc

MALLOC(3) Linux Programmer’s Manual MALLOC(3) 名前 calloc, malloc, free, realloc - 動的なメモリの割り当てと解放を行う 書式 #include void *calloc(size_t nmemb, size_t size); void *malloc(size_t size); void free(void *ptr); void *realloc(void *ptr, size_t size); 説明 calloc() は size バイトの要素 nmemb 個からなる配列にメモリを割り当て、 割り当てられたメモリに対するポインタを返す。メモリの内容は数値ゼロ ( 全 ビットがゼロのバイト) にセットされる。 nmemb か size が 0 の場合、 cal- loc() は NULL または free() に後で渡しても問題の起こらない一意なポイ ン タ値を返す。 malloc() は size バイトを割り当て、割り当てられたメモリに対するポインタ を返す。メモリの内容はクリアされない。 size が 0 の場合、 malloc() は NULL または free() に後で渡しても問題の起こらない一意なポインタ値を返す 。 free() はポインタ ptr が指すメモリ空間を解放する。このポインタは、以 前 に呼び出された malloc(), calloc(), realloc() のいずれかが返した値でなけ ればならない。これ以外のポインタを指定したり、すでに free(ptr) が実行さ れていたりした場合の動作は定義されていない。 ptr が NULL の場合には、な んの動作も行われない。 realloc() は、ポインタ ptr が示すメモリブロックのサイズを変更して size バ イトにする。新旧のサイズのうち、小さいほうのブロックに含まれる内容は 変更されない。新しく割り当てられたメモリの内容は初期化されない 。 size がどの値であっても、 ptr が NULL の場合には malloc(size) と等価である。 size が 0 で ptr が NULL でない場合には、 free(ptr) と等価である。 ptr が NULL 以外の場合、 ptr は以前に呼び出された malloc(), calloc(), real- loc() のいずれかが返した値でなければならない。 ptr が指す領域が移動され ていた場合は free(ptr) が実行される。 返り値 calloc() と malloc() は、割り当てられたメモリへのポインタを返す。割り当 てられたメモリは、あらゆる種類の変数に対応できるようにアラインメント さ れている。エラーの場合、これらの関数は NULL を返す。 size が 0 で呼び出 した malloc() や、 nmemb か size が 0 で呼び出した calloc() が成功し た 場合にも NULL が返される。 free() は値を返さない。 realloc() は新たに割り当てられたメモリへのポインタを返す。これはあらゆ る種類の変数に対応できるようにアラインメントされており、 ptr とは異なる こともある。割り当て要求に失敗した場合は NULL が返る。 size が 0 の場合 には、NULL もしくは free() に渡すことができるポインタが返る。 realloc() が 失敗した場合には、元のブロックは変更されない。つまり、解放されたり移 動されたりはしない。 準拠 C89, C99. 注意 通常、 malloc() は、ヒープからメモリを割り当て、必要に応じてヒープの サ イズを sbrk(2) を使って調節する。 MMAP_THRESHOLD バイトよりも大きなメモ リブロックを割り当てる場合、 glibc の malloc() 実装は mmap(2) を使っ て プライベートな無名マッピング (anonymous mapping) としてメモリを割り当て る。デフォルトでは MMAP_THRESHOLD は 128 kB だが、 mallopt(3) を使っ て 調 整できる。 mmap(2) を使って行われたメモリ割り当ては RLIMIT_DATA リソ ース上限の影響を受けない (getrlimit(2) 参照)。 Unix98 標準では、 malloc(), calloc(), realloc() は実行に失敗したとき に errno を ENOMEM に設定することになっている。 Glibc ではこれが守られてい ることを仮定している (またこれらのルーチンの glibc バージョンはこのこと を 守 っている)。個人的に別の malloc の実装を使っていて、その malloc が errno を設定しない場合には、失敗した際に errno にエラーの理由を設定しな いライブラリルーチンがあるかもしれない。 malloc(), calloc(), realloc(), free() における事故は、ほとんどの場合は ヒープの破壊 (corruption) が原因である。例えば、割り当てられた領域を オ ーバーフローする、同じポインタに二度 free する、などがこれにあたる。 最 近のバージョンの Linux libc (5.4.23 以降) と glibc (2.x) では、 mal- loc() の動作を環境変数によって制御できるような実装がされている 。 MAL- LOC_CHECK_ が設定されていると、特殊な実装が用いられ、単純なエラーには耐 えることができるようになる (効率は悪くなる)。例えば、 free() を同じ引き 数 で二度呼び出してしまう、 1 バイトだけ行きすぎてしまう (off-by-one バ グ) などがこれに当たる。しかし、これらのエラーの全てを防ぐことができ る わ けではなく、その場合にはメモリリークが起こってしまう。 MALLOC_CHECK_ が 0 にセットされていると、ヒープの破壊を黙って無視する。 1 にセット さ れていると、診断メッセージが標準エラー出力に表示される。 2 にセットされ ていると、ただちに abort(3) が呼び出される。 3 にセットされていると、診 断メッセージが標準エラー出力に表示され、プログラムは強制終了 (abort) さ れる。 MALLOC_CHECK_ に 0 以外の値をセットして役に立つ状況としては、 実 際 のプロセスのクラッシュがずっと後に起こり、本当の原因を探し出すのが非 常に困難な場合などが挙げられるだろう。 バグ デフォルトでは、Linux は楽観的メモリ配置戦略を用いている。つまり、 mal- loc() が NULL でない値を返しても、そのメモリが実際に利用可能であること が保証されない。これは本当にまずいバグである。システムがメモリ不足状 態 に なったとき、悪名高いメモリ不足解決器 (OOM killer) によって一つまたは 複数のプロセスが削除される。突然あるプロセスが削除されるのが望ましく な い 状況で使用されていて、しかもカーネルのバージョンが十分に最近のもので あれば、このメモリを割り当て過ぎる動作 (overcommitting behavior) を以下 のコマンドで無効にできる。 # echo 2 > /proc/sys/vm/overcommit_memory カーネルの付属文書の vm/overcommit-accounting と sysctl/vm.txt も参照の こと。 関連項目 brk(2), posix_memalign(3) mmap(2), alloca(3), GNU 2009-01-13 MALLOC(3)

MALLOC(3) Linux Programmer’s Manual MALLOC(3) NAME calloc, malloc, free, realloc - Allocate and free dynamic memory SYNOPSIS #include void *calloc(size_t nmemb, size_t size); void *malloc(size_t size); void free(void *ptr); void *realloc(void *ptr, size_t size); DESCRIPTION calloc() allocates memory for an array of nmemb elements of size bytes each and returns a pointer to the allocated memory. The memory is set to zero. If nmemb or size is 0, then calloc() returns either NULL, or a unique pointer value that can later be successfully passed to free(). malloc() allocates size bytes and returns a pointer to the allocated memory. The memory is not cleared. If size is 0, then malloc() returns either NULL, or a unique pointer value that can later be suc- cessfully passed to free(). free() frees the memory space pointed to by ptr, which must have been returned by a previous call to malloc(), calloc() or realloc(). Other- wise, or if free(ptr) has already been called before, undefined behav- ior occurs. If ptr is NULL, no operation is performed. realloc() changes the size of the memory block pointed to by ptr to size bytes. The contents will be unchanged to the minimum of the old and new sizes; newly allocated memory will be uninitialized. If ptr is NULL, then the call is equivalent to malloc(size), for all values of size; if size is equal to zero, and ptr is not NULL, then the call is equivalent to free(ptr). Unless ptr is NULL, it must have been returned by an earlier call to malloc(), calloc() or realloc(). If the area pointed to was moved, a free(ptr) is done. RETURN VALUE For calloc() and malloc(), return a pointer to the allocated memory, which is suitably aligned for any kind of variable. On error, these functions return NULL. NULL may also be returned by a successful call to malloc() with a size of zero, or by a successful call to calloc() with nmemb or size equal to zero. free() returns no value. realloc() returns a pointer to the newly allocated memory, which is suitably aligned for any kind of variable and may be different from ptr, or NULL if the request fails. If size was equal to 0, either NULL or a pointer suitable to be passed to free() is returned. If realloc() fails the original block is left untouched; it is not freed or moved. CONFORMING TO C89, C99. NOTES Normally, malloc() allocates memory from the heap, and adjusts the size of the heap as required, using sbrk(2). When allocating blocks of mem- ory larger than MMAP_THRESHOLD bytes, the glibc malloc() implementation allocates the memory as a private anonymous mapping using mmap(2). MMAP_THRESHOLD is 128 kB by default, but is adjustable using mal- lopt(3). Allocations performed using mmap(2) are unaffected by the RLIMIT_DATA resource limit (see getrlimit(2)). The Unix98 standard requires malloc(), calloc(), and realloc() to set errno to ENOMEM upon failure. Glibc assumes that this is done (and the glibc versions of these routines do this); if you use a private malloc implementation that does not set errno, then certain library routines may fail without having a reason in errno. Crashes in malloc(), calloc(), realloc(), or free() are almost always related to heap corruption, such as overflowing an allocated chunk or freeing the same pointer twice. Recent versions of Linux libc (later than 5.4.23) and glibc (2.x) include a malloc() implementation which is tunable via environment variables. When MALLOC_CHECK_ is set, a special (less efficient) implementation is used which is designed to be tolerant against simple errors, such as double calls of free() with the same argument, or over- runs of a single byte (off-by-one bugs). Not all such errors can be protected against, however, and memory leaks can result. If MAL- LOC_CHECK_ is set to 0, any detected heap corruption is silently ignored; if set to 1, a diagnostic message is printed on stderr; if set to 2, abort(3) is called immediately; if set to 3, a diagnostic message is printed on stderr and the program is aborted. Using a non-zero MAL- LOC_CHECK_ value can be useful because otherwise a crash may happen much later, and the true cause for the problem is then very hard to track down. BUGS By default, Linux follows an optimistic memory allocation strategy. This means that when malloc() returns non-NULL there is no guarantee that the memory really is available. This is a really bad bug. In case it turns out that the system is out of memory, one or more pro- cesses will be killed by the infamous OOM killer. In case Linux is employed under circumstances where it would be less desirable to sud- denly lose some randomly picked processes, and moreover the kernel ver- sion is sufficiently recent, one can switch off this overcommitting behavior using a command like: # echo 2 > /proc/sys/vm/overcommit_memory See also the kernel Documentation directory, files vm/overcommit- accounting and sysctl/vm.txt. SEE ALSO brk(2), mmap(2), alloca(3), posix_memalign(3) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. GNU 2009-01-13 MALLOC(3)