.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Paul Kranenburg.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the NetBSD
.\" Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.\" %NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp %
.\" %FreeBSD: src/share/man/man9/malloc.9,v 1.13.2.2 2001/03/06 19:08:22 ru Exp %
.\"
.Dd June 16, 1996
.Dt MALLOC 9
.Os FreeBSD
.Sh 名称
.Nm malloc ,
.Nm MALLOC ,
.Nm free ,
.Nm FREE
.Nd カーネルメモリマネージメントルーチン
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <sys/malloc.h>
.Ft void *
.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags"
.Ft void
.Fn free "void *addr" "struct malloc_type *type"
.Fn FREE "void *addr" "struct malloc_type *type"
.Sh 解説
.Fn malloc
関数はカーネルアドレス空間の初期化されていないメモリを
.Fa size
で指定された大きさの 1 つのオブジェクトとして割り当てます。
.Fn free
は
.Fn malloc
で先に割り当てられていた
.Fa addr
のアドレスのメモリを再使用するために開放します。
メモリは 0 にクリアされません。
マクロ版の
.Fn MALLOC
は機能的には
.Bd -literal -offset indent
(space) = (cast)malloc((u_long)(size), type, flags)
.Ed
.Pp
と同等で、
マクロ版
.Fn FREE
は
.Bd -literal -offset indent
free((addr), type)
.Ed
.Pp
と同等です。
標準Cライブラリの同義関数
.Pq Xr malloc 3
とは異なり、カーネルバージョンは更に 2 つの引き数をとります。
引き数
.Fa flags
は
.Fn malloc
の操作上の特性を以下のようにみなします。
.Bl -tag -width M_NOWAIT
.It Dv M_NOWAIT
リソースの不足のため直ちに要求を満たすことができない場合は、
.Fn malloc
が
.Dv NULL
を返すようにします。
通常は、
.Fn malloc
は他のプロセスによるリソースの開放を待つために
.Fn sleep
を呼び出すでしょう。
このフラグがセットされていれば、
.Fn malloc
はブロックせずに
.Dv NULL
を返します。
.Dv M_WAITOK
が 0 に定義されていることに注意してください。
これはブロッキング操作がデフォルトだということです。
.It Dv M_ASLEEP
リソースの不足のため直ちに要求を満たすことができない場合は、
.Fn malloc
が
.Fn asleep
を呼ぶようにします。
.Dv M_ASLEEP
の単独での使用は実用的ではなく、常に
.Dv M_NOWAIT
との論理和(OR)をとって
.Fn malloc
に
.Fn asleep
を呼ばせ、直ちに
.Dv NULL
を返させます。
呼び出し側がある時点で
.Fn await
を呼び、割り当てのリトライをすることが期待されています。
当のルーチンに依存して、呼び出し側で一時的な失敗を上位に連鎖的に伝搬し、実際に
.Fn malloc
がキューに入れた非同期のウェイトをブロックする
幾つかの別の高レベルルーチンをもつことを決めることも出来ます。
.It Dv M_WAITOK
リソースを待つことが可能(OK)であることを示します。
都合の悪いことに 0 と定義されているので、直接この値に対して比較したり、
フラグとして論理積(AND)をとったりしないように注意されなければなりません。
デフォルトの操作はメモリの割り当てが成功するまでブロックします。
.Dv M_NOWAIT
が指定されると
.Fn malloc
は単に
.Dv NULL
を返すことが出来ます。
.It Dv M_USE_RESERVE
要求されたメモリを獲得するために、
システムがリザーブ領域を使ってよいことを示します。
このオプションは以前は M_KERNEL と呼ばれていましたが、
より明示的に改名されました。
このオプションは軽視されていて、カーネルから徐々に削除されています。
そのため、新たなプログラミングでは使用されない様にするべきです。
.El
.Pp
引き数
.Fa type
はメモリの利用方法の統計をとるためと、
簡単なサニティチェックのために使われています。
この統計は
.Sq vmstat -m
で調べることが出来ます。
.Pp
.Fa type
は
.Fn MALLOC_DECLARE
と
.Fn MALLOC_DEFINE
マクロを通じて
.Va malloc_type_t
typedef を使用して定義されます。
.Bd -literal -offset indent
/* sys/something/foo_extern.h */
MALLOC_DECLARE(M_FOOBUF);
/* sys/something/foo_main.c */
MALLOC_DEFINE(M_FOOBUF, "foobuffers",
"Buffers to foo data into the ether");
/* sys/something/foo_subr.c */
\&...
MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
.Ed
.Pp
.Sh 戻り値
.Fn malloc
はすべてのタイプのオブジェクトの格納に適切なように整列された
カーネル仮想アドレスを、
または要求が満足できずかつ
.Dv M_NOWAIT
がセットされている場合に
.Dv NULL
を返します。
.Dv M_ASLEEP
がセットされていて
.Fn malloc
が
.Dv NULL
を返す場合、副作用として
.Fn asleep
が呼び出されます。
.Sh 関連項目
.Xr vmstat 8
.Sh 診断
.Dv DIAGNOSTIC
コンフィギュレーションオプションを付けてコンパイルされたカーネルは、
割り当てられた領域以外への書き込みや
.Fn malloc
関数と
.Fn free
関数の不均衡な呼び出しなどにより生じたメモリ不正の検出を試みます。
一貫性チェックの失敗はパニックまたはシステムコンソールメッセージを出力します。
.Bl -bullet -offset indent -compact
.Pp
.It
panic:
.Dq malloc: bogus type
.It
panic:
.Dq malloc: allocation too large
.It
panic:
.Dq malloc: wrong bucket
.It
panic:
.Dq malloc: lost data
.It
panic:
.Dq free: address 0x%x out of range
.It
panic:
.Dq free: type %d out of range
.It
panic:
.Dq free: unaligned addr Aq description of object
.It
panic:
.Dq free: item modified
.It
panic:
.Dq free: multiple free[s]
.It
.Dq Data modified on freelist: Aq description of object
.El
