release/man3/posix_memalign.3

   1 .\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk>
   2 .\" Based in part on GNU libc documentation.
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" License.
  24 .\"
  25 .\" 2001-10-11, 2003-08-22, aeb, added some details
  26 .\"
  27 .\" Japanese Version Copyright (c) 2001 Akihiro MOTOKI
  28 .\"       all rights reserved.
  29 .\" Translated 2001-11-05, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  30 .\" Updated 2003-09-05, Akihiro MOTOKI, catch up to v1.60
  31 .\" Updated 2005-11-19, Akihiro MOTOKI
  32 .\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24
  33 .\"
  34 .\"WORD:        obsolete        廃止された
  35 .\"WORD:        a multiple of   〜の倍数
  36 .\"WORD:        a power of two  2 のべき乗
  37 .\"
  38 .TH POSIX_MEMALIGN 3  2010-09-20 "GNU" "Linux Programmer's Manual"
  39 .SH 名前
  40 posix_memalign, memalign, valloc \- アラインメントされたメモリの割り当てを行う
  41 .SH 書式
  42 .nf
  43 .B #include <stdlib.h>
  44 .sp
  45 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
  46 .sp
  47 .B #include <malloc.h>
  48 .sp
  49 .BI "void *valloc(size_t " size );
  50 .BI "void *memalign(size_t " boundary ", size_t " size );
  51 .fi
  52 .sp
  53 .in -4n
  54 glibc 向けの機能検査マクロの要件
  55 .RB ( feature_test_macros (7)
  56 参照):
  57 .in
  58 .sp
  59 .ad l
  60 .BR posix_memalign ():
  61 .RS 4
  62 _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  63 .RE
  64 .sp
  65 .BR valloc ():
  66 .br
  67 .PD 0
  68 .RS 4
  69 .TP 4
  70 glibc 2.12 以降:
  71 .nf
  72 _BSD_SOURCE ||
  73     (_XOPEN_SOURCE\ >=\ 500 ||
  74         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  75     !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
  76 .br
  77 .fi
  78 .TP
  79 glibc 2.12 より前:
  80 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  81 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  82 .RE
  83 .PD
  84 .ad b
  85 .SH 説明
  86 関数
  87 .BR posix_memalign ()
  88 は、
  89 .I size
  90 バイトのメモリを割り当て、割り当てられたメモリのアドレスを
  91 .I "*memptr"
  92 に設定する。
  93 割り当てられたメモリのアドレスは
  94 .I "alignment"
  95 の倍数になっているはずである。
  96 .I "alignment"
  97 は 2 のべき乗で、かつ
  98 .IR "sizeof(void *)"
  99 の倍数でなければならない。
 100 .I size
 101 が 0 の場合、
 102 .BR posix_memalign ()
 103 は NULL か一意なポインタ値を返す。
 104 このポインタ値は、後で
 105 .BR free (3)
 106 に問題なく渡すことができる。
 107
 108 廃止された関数である
 109 .BR memalign ()
 110 は、
 111 .I size
 112 バイトのメモリを割り当て、割り当てられたメモリへのポインタを返す。
 113 メモリのアドレスは
 114 .I "boundary"
 115 の倍数になっているはずである。
 116 .I "boundary"
 117 は 2 のべき乗でなければならない。
 118 .\" The behavior of memalign() for size==0 is as for posix_memalign()
 119 .\" but no standards govern this.
 120
 121 廃止された関数である
 122 .BR valloc ()
 123 は
 124 .I size
 125 バイトのメモリを割り当て、割り当てられたメモリへのポインタを返す。
 126 メモリのアドレスはページサイズの倍数になっているはずである。
 127 これは
 128 .I "memalign(sysconf(_SC_PAGESIZE),size)"
 129 と等価である。
 130
 131 .\" motoki: be not zeroed ってどういう意味？
 132 3 つの関数はいずれもメモリのゼロクリアを行わない。
 133 .SH 返り値
 134 .BR memalign ()
 135 と
 136 .BR valloc ()
 137 は割り当てられたメモリへのポインタを返す。
 138 割り当てに失敗した場合は NULL を返す。
 139
 140 .BR posix_memalign ()
 141 は成功した場合は 0 を返し、
 142 失敗した場合は次のセクションに記載されたエラー値のいずれかを返す。
 143 .I errno
 144 はセットされないことに注意すること。
 145 .SH エラー
 146 .TP
 147 .B EINVAL
 148 .I alignment
 149 引き数が 2 のべき乗でなかったか、
 150 .IR "sizeof(void *)"
 151 の倍数でなかった。
 152 .TP
 153 .B ENOMEM
 154 割り当て要求を満たすのに十分なメモリがなかった。
 155 .SH バージョン
 156 .BR memalign ()
 157 と
 158 .BR valloc ()
 159 はすべての Linux libc ライブラリで使用可能である。
 160 .BR posix_memalign ()
 161 は glibc 2.1.91 以降で使用可能である。
 162 .SH 準拠
 163 関数
 164 .BR valloc ()
 165 は 3.0BSD で登場した。4.3BSD では廃止されたと記載されており、
 166 SUSv2 では過去の名残だと記載されている。
 167 POSIX.1-2001 にはもはや存在しない。
 168 関数
 169 .BR memalign ()
 170 は SunOS 4.1.3 で登場したが、4.4BSD にはない。
 171 関数
 172 .BR posix_memalign ()
 173 は POSIX.1d に由来する。
 174 .SS ヘッダ
 175 .BR posix_memalign ()
 176 の宣言を \fI<stdlib.h>\fP で行うことに関しては、
 177 皆の意見が一致している。
 178
 179 いくつかのシステムでは、
 180 .BR memalign ()
 181 は \fI<malloc.h>\fP ではなく \fI<stdlib.h>\fP で宣言されている。
 182
 183 SUSv2 によると、
 184 .BR valloc ()
 185 は
 186 .I <stdlib.h>
 187 で宣言される。
 188 libc4,5 や glibc では
 189 .I <malloc.h>
 190 で宣言されており、
 191 さらに
 192 .I <stdlib.h>
 193 でも宣言されることもある
 194 (具体的には以下のいずれかの場合:
 195 .B _GNU_SOURCE
 196 が定義されている、
 197 .B _BSD_SOURCE
 198 が定義されている、
 199 glibc で
 200 .B _XOPEN_SOURCE_EXTENDED
 201 が定義されている、
 202 glibc で
 203 .B _XOPEN_SOURCE
 204 が 500 より小さくない値に定義されている)。
 205 .SH 注意
 206 多くのシステムでは、アラインメントに関して制限がある。例えば、
 207 ブロックデバイスに対するダイレクト I/O に使用するバッファには
 208 アラインメントに関する制限がある。
 209 POSIX では、どんなアラインメントが必要かを知るために
 210 .I "pathconf(path,_PC_REC_XFER_ALIGN)"
 211 コールを規定している。ここで
 212 .BR posix_memalign ()
 213 を使うと、この必要条件を満たすことができる。
 214
 215 .BR posix_memalign ()
 216 は
 217 .I alignment
 218 が上で詳細に述べた必要条件を満たすかどうかを確かめる。
 219 .BR memalign ()
 220 は
 221 .I boundary
 222 引き数が正しいかどうかの確認を行わないかもしれない。
 223
 224 POSIX では
 225 .BR posix_memalign ()
 226 によって獲得したメモリは
 227 .BR free (3)
 228 を使って解放することができる必要がある。
 229 いくつかのシステムでは
 230 .BR memalign ()
 231 や
 232 .BR valloc ()
 233 で割り当てられたメモリを再利用する手段が提供されていない。
 234 .\" motoki: while の前後のつながりはこれでいい？
 235 (なぜなら
 236 .BR free (3)
 237 に渡すことができるのは
 238 .BR malloc (3)
 239 から受け取ったポインタだけだが、
 240 例えば
 241 .BR memalign ()
 242 は
 243 .BR malloc (3)
 244 を呼び出し、得た値をアラインメントしてしまうからである)
 245 .\" Other systems allow passing the result of
 246 .\" .BR valloc ()
 247 .\" to
 248 .\" .BR free (3),
 249 .\" but not to
 250 .\" .BR realloc (3).
 251 glibc の実装では、
 252 ここに述べた 3 つの関数のいずれで獲得したメモリも
 253 .BR free (3)
 254 で再利用することができる。
 255
 256 glibc の
 257 .BR malloc (3)
 258 は常に 8 バイトにアラインメントされたメモリアドレスを返すので、
 259 ここで述べた関数が必要になるのは
 260 8 バイトよりも大きなアラインメントが必要な場合だけである。
 261 .SH 関連項目
 262 .BR brk (2),
 263 .BR getpagesize (2),
 264 .BR free (3),
 265 .BR malloc (3)