1 .\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk>
2 .\" Based in part on GNU libc documentation.
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" 2001-10-11, 2003-08-22, aeb, added some details
27 .\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com>
28 .\" Document pvalloc() and aligned_alloc()
29 .\"*******************************************************************
31 .\" This file was generated with po4a. Translate the source file.
33 .\"*******************************************************************
34 .TH POSIX_MEMALIGN 3 2012\-03\-23 GNU "Linux Programmer's Manual"
36 posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- アラインメント
40 \fB#include <stdlib.h>\fP
42 \fBint posix_memalign(void **\fP\fImemptr\fP\fB, size_t \fP\fIalignment\fP\fB, size_t \fP\fIsize\fP\fB);\fP
43 \fBvoid *aligned_alloc(size_t \fP\fIalignment\fP\fB, size_t \fP\fIsize\fP\fB);\fP
44 \fBvoid *valloc(size_t \fP\fIsize\fP\fB);\fP
46 \fB#include <malloc.h>\fP
48 \fBvoid *memalign(size_t \fP\fIalignment\fP\fB, size_t \fP\fIsize\fP\fB);\fP
49 \fBvoid *pvalloc(size_t \fP\fIsize\fP\fB);\fP
53 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照):
57 \fBposix_memalign\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
59 \fBaligned_alloc\fP(): _ISOC11_SOURCE
69 (_XOPEN_SOURCE\ >=\ 500 ||
70 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
71 !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
76 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
79 ((非標準の) ヘッダファイル \fI<malloc.h>\fP も
80 \fBvalloc\fP() の宣言も公開する。機能検査マクロは不要である。
85 関数 \fBposix_memalign\fP() は、 \fIsize\fP バイトのメモリを割り当て、割り当てられたメモリのアドレスを \fI*memptr\fP
86 に設定する。 割り当てられたメモリのアドレスは \fIalignment\fP の倍数になっているはずである。 \fIalignment\fP は 2
87 のべき乗で、かつ \fIsizeof(void\ *)\fP の倍数でなければならない。 \fIsize\fP が 0 の場合、
88 \fBposix_memalign\fP() は NULL か一意なポインタ値を返す。 このポインタ値は、後で \fBfree\fP(3)
91 .\" The behavior of memalign() for size==0 is as for posix_memalign()
92 .\" but no standards govern this.
93 廃止された関数である \fBmemalign\fP() は、 \fIsize\fP バイトのメモリを割り当て、
94 割り当てられたメモリへのポインタを返す。 メモリのアドレスは \fIalignment\fP
95 の倍数になっているはずである。 \fIalignment\fP は 2 のべき乗でなければならない。
97 関数 \fBaligned_alloc\fP() は \fBmemalign\fP() と同じだが、\fIsize\fP が \fIalignment\fP
98 の倍数でなければならないという追加の制限がある点が異なる。
100 廃止された関数である \fBvalloc\fP() は \fIsize\fP バイトのメモリを割り当て、割り当てられたメモリへのポインタを返す。
101 メモリのアドレスはページサイズの倍数になっているはずである。 これは \fImemalign(sysconf(_SC_PAGESIZE),size)\fP
104 廃止された関数 \fBpvalloc\fP() は \fBvalloc\fP() と同様だが、
105 割り当てられるサイズがシステムのページサイズの倍数に切り上げられる。
107 これらの関数はいずれもメモリのゼロクリアを行わない。
109 \fBaligned_alloc\fP(), \fBmemalign\fP(), \fBvalloc\fP(), \fBpvalloc\fP() は割り当てられた
110 メモリへのポインタを返す。 割り当てに失敗した場合は NULL を返す。
112 \fBposix_memalign\fP() は成功した場合は 0 を返し、 失敗した場合は次のセクションに記載されたエラー値のいずれかを返す。
113 \fIerrno\fP はセットされないことに注意すること。
117 \fIalignment\fP 引き数が 2 のべき乗でなかったか、 \fIsizeof(void\ *)\fP の倍数でなかった。
120 割り当て要求を満たすのに十分なメモリがなかった。
122 関数 \fBmemalign\fP(), \fBvalloc\fP(), \fBpvalloc\fP() は
123 すべての Linux libc ライブラリで使用可能である。
125 関数 \fBaligned_alloc\fP() は glibc バージョン 2.16 で追加された。
127 関数 \fBposix_fallocate\fP() は glibc 2.1.91 以降で利用可能である。
129 関数 \fBvalloc\fP() は 3.0BSD で登場した。4.3BSD では廃止されたと記載されており、
130 SUSv2 では過去の名残だと記載されている。 POSIX.1\-2001 には存在しない。
132 関数 \fBpvalloc\fP() は GNU による拡張である。
134 関数 \fBmemalign\fP() は SunOS 4.1.3 で登場したが、4.4BSD にはない。
136 関数 \fBposix_memalign\fP() は POSIX.1d に由来する。
139 関数 \fIaligned_alloc\fP() は C11 標準で規定されている。
141 \fBposix_memalign\fP() の宣言を \fI<stdlib.h>\fP で行うことに関しては、 皆の意見が一致している。
143 いくつかのシステムでは、 \fBmemalign\fP() は \fI<malloc.h>\fP ではなく
144 \fI<stdlib.h>\fP で宣言されている。
146 SUSv2 によると、 \fBvalloc\fP() は \fI<stdlib.h>\fP で宣言される。 libc4,5
147 や glibc では \fI<malloc.h>\fP で宣言されており、 さらに適切な機能検査
148 マクロが定義された場合には \fI<stdlib.h>\fP でも宣言される(上記を参照)。
150 多くのシステムでは、アラインメントに関して制限がある。例えば、 ブロックデバイスに対するダイレクト I/O に使用するバッファには
151 アラインメントに関する制限がある。 POSIX では、どんなアラインメントが必要かを知るために
152 \fIpathconf(path,_PC_REC_XFER_ALIGN)\fP コールを規定している。ここで \fBposix_memalign\fP()
153 を使うと、この必要条件を満たすことができる。
155 \fBposix_memalign\fP() は \fIalignment\fP が上で詳細に述べた必要条件を満たすか
156 どうかを確かめる。 \fBmemalign\fP() は \fIalignment\fP 引き数が正しいかどうかの
159 .\" Other systems allow passing the result of
165 POSIX では \fBposix_memalign\fP() によって獲得したメモリは \fBfree\fP(3) を
166 使って解放することができる必要がある。 いくつかのシステムでは
167 \fBmemalign\fP() や\fBvalloc\fP() で割り当てられたメモリを再利用する手段が
168 提供されていない(なぜなら \fBfree\fP(3) に渡すことができるのは
169 \fBmalloc\fP(3) から受け取ったポインタだけだが、例えば \fBmemalign\fP() は
170 \fBmalloc\fP(3) を呼び出し、得た値をアラインメントしてしまうからである)。
171 glibc の実装では、 ここに述べた関数のいずれで獲得したメモリも
172 \fBfree\fP(3) で再利用することができる。
174 glibc の \fBmalloc\fP(3) は常に 8 バイトにアラインメントされたメモリアドレスを
175 返すので、ここで述べた関数が必要になるのは 8 バイトよりも大きなアラインメント
178 \fBbrk\fP(2), \fBgetpagesize\fP(2), \fBfree\fP(3), \fBmalloc\fP(3)
180 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
181 である。プロジェクトの説明とバグ報告に関する情報は
182 http://www.kernel.org/doc/man\-pages/ に書かれている。