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 .\" %%%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.
   8 .\"
   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.
  13 .\"
  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
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  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 .\"*******************************************************************
  30 .\"
  31 .\" This file was generated with po4a. Translate the source file.
  32 .\"
  33 .\"*******************************************************************
  34 .\"
  35 .\" Japanese Version Copyright (c) 2001 Akihiro MOTOKI
  36 .\"       all rights reserved.
  37 .\" Translated 2001-11-05, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  38 .\" Updated 2003-09-05, Akihiro MOTOKI, catch up to v1.60
  39 .\" Updated 2005-11-19, Akihiro MOTOKI
  40 .\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24
  41 .\" Updated 2012-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  42 .\" Updated 2012-05-08, Akihiro MOTOKI <amotoki@gmail.com>
  43 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  44 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  45 .\"
  46 .TH POSIX_MEMALIGN 3 2013\-09\-02 GNU "Linux Programmer's Manual"
  47 .SH 名前
  48 posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- アラインメント
  49 されたメモリの割り当てを行う
  50 .SH 書式
  51 .nf
  52 \fB#include <stdlib.h>\fP
  53 .sp
  54 \fBint posix_memalign(void **\fP\fImemptr\fP\fB, size_t \fP\fIalignment\fP\fB, size_t \fP\fIsize\fP\fB);\fP
  55 \fBvoid *aligned_alloc(size_t \fP\fIalignment\fP\fB, size_t \fP\fIsize\fP\fB);\fP
  56 \fBvoid *valloc(size_t \fP\fIsize\fP\fB);\fP
  57 .sp
  58 \fB#include <malloc.h>\fP
  59 .sp
  60 \fBvoid *memalign(size_t \fP\fIalignment\fP\fB, size_t \fP\fIsize\fP\fB);\fP
  61 \fBvoid *pvalloc(size_t \fP\fIsize\fP\fB);\fP
  62 .fi
  63 .sp
  64 .in -4n
  65 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  66 .in
  67 .sp
  68 .ad l
  69 \fBposix_memalign\fP(): _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  70 .sp
  71 \fBaligned_alloc\fP(): _ISOC11_SOURCE
  72 .sp
  73 \fBvalloc\fP():
  74 .br
  75 .PD 0
  76 .RS 4
  77 .TP  4
  78 glibc 2.12 以降:
  79 .nf
  80 _BSD_SOURCE ||
  81     (_XOPEN_SOURCE\ >=\ 500 ||
  82         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  83     !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
  84 .br
  85 .fi
  86 .TP
  87 glibc 2.12 より前:
  88 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  89 .ad b
  90 .br
  91 ((非標準の) ヘッダファイル \fI<malloc.h>\fP も
  92 \fBvalloc\fP() の宣言も公開する。機能検査マクロは不要である。
  93 .RE
  94 .PD
  95 .SH 説明
  96 .\" glibc does this:
  97 The function \fBposix_memalign\fP()  allocates \fIsize\fP bytes and places the
  98 address of the allocated memory in \fI*memptr\fP.  The address of the allocated
  99 memory will be a multiple of \fIalignment\fP, which must be a power of two and
 100 a multiple of \fIsizeof(void\ *)\fP.  If \fIsize\fP is 0, then the value placed in
 101 \fI*memptr\fP is either NULL, or a unique pointer value that can later be
 102 successfully passed to \fBfree\fP(3).
 103
 104 .\" The behavior of memalign() for size==0 is as for posix_memalign()
 105 .\" but no standards govern this.
 106 廃止された関数である \fBmemalign\fP() は、 \fIsize\fP バイトのメモリを割り当て、
 107 割り当てられたメモリへのポインタを返す。 メモリのアドレスは \fIalignment\fP
 108 の倍数になっているはずである。 \fIalignment\fP は 2 のべき乗でなければならない。
 109
 110 関数 \fBaligned_alloc\fP() は \fBmemalign\fP() と同じだが、\fIsize\fP が \fIalignment\fP
 111 の倍数でなければならないという追加の制限がある点が異なる。
 112
 113 廃止された関数である \fBvalloc\fP()  は \fIsize\fP バイトのメモリを割り当て、割り当てられたメモリへのポインタを返す。
 114 メモリのアドレスはページサイズの倍数になっているはずである。 これは \fImemalign(sysconf(_SC_PAGESIZE),size)\fP
 115 と等価である。
 116
 117 廃止された関数 \fBpvalloc\fP() は \fBvalloc\fP() と同様だが、
 118 割り当てられるサイズがシステムのページサイズの倍数に切り上げられる。
 119
 120 これらの関数はいずれもメモリのゼロクリアを行わない。
 121 .SH 返り値
 122 \fBaligned_alloc\fP(), \fBmemalign\fP(), \fBvalloc\fP(), \fBpvalloc\fP() は割り当てられた
 123 メモリへのポインタを返す。 割り当てに失敗した場合は NULL を返す。
 124
 125 \fBposix_memalign\fP()  returns zero on success, or one of the error values
 126 listed in the next section on failure.  The value of \fIerrno\fP is
 127 indeterminate after a call to \fBposix_memalign\fP().
 128 .SH エラー
 129 .TP
 130 \fBEINVAL\fP
 131 \fIalignment\fP 引き数が 2 のべき乗でなかったか、 \fIsizeof(void\ *)\fP の倍数でなかった。
 132 .TP
 133 \fBENOMEM\fP
 134 割り当て要求を満たすのに十分なメモリがなかった。
 135 .SH バージョン
 136 関数 \fBmemalign\fP(), \fBvalloc\fP(), \fBpvalloc\fP() は
 137 すべての Linux libc ライブラリで使用可能である。
 138
 139 関数 \fBaligned_alloc\fP() は glibc バージョン 2.16 で追加された。
 140
 141 関数 \fBposix_fallocate\fP() は glibc 2.1.91 以降で利用可能である。
 142 .SH 準拠
 143 関数 \fBvalloc\fP() は 3.0BSD で登場した。4.3BSD では廃止されたと記載されており、
 144 SUSv2 では過去の名残だと記載されている。 POSIX.1\-2001 には存在しない。
 145
 146 関数 \fBpvalloc\fP() は GNU による拡張である。
 147
 148 関数 \fBmemalign\fP() は SunOS 4.1.3 で登場したが、4.4BSD にはない。
 149
 150 関数 \fBposix_memalign\fP() は POSIX.1d に由来する。
 151
 152 .\"
 153 関数 \fIaligned_alloc\fP() は C11 標準で規定されている。
 154 .SS ヘッダ
 155 \fBposix_memalign\fP()  の宣言を \fI<stdlib.h>\fP で行うことに関しては、 皆の意見が一致している。
 156
 157 いくつかのシステムでは、 \fBmemalign\fP()  は \fI<malloc.h>\fP ではなく
 158 \fI<stdlib.h>\fP で宣言されている。
 159
 160 SUSv2 によると、 \fBvalloc\fP() は \fI<stdlib.h>\fP で宣言される。 libc4,5
 161 や glibc では \fI<malloc.h>\fP で宣言されており、 さらに適切な機能検査
 162 マクロが定義された場合には \fI<stdlib.h>\fP でも宣言される(上記を参照)。
 163 .SH 注意
 164 多くのシステムでは、アラインメントに関して制限がある。例えば、 ブロックデバイスに対するダイレクト I/O に使用するバッファには
 165 アラインメントに関する制限がある。 POSIX では、どんなアラインメントが必要かを知るために
 166 \fIpathconf(path,_PC_REC_XFER_ALIGN)\fP コールを規定している。ここで \fBposix_memalign\fP()
 167 を使うと、この必要条件を満たすことができる。
 168
 169 \fBposix_memalign\fP() は \fIalignment\fP が上で詳細に述べた必要条件を満たすか
 170 どうかを確かめる。 \fBmemalign\fP() は \fIalignment\fP 引き数が正しいかどうかの
 171 確認を行わないかもしれない。
 172
 173 .\" Other systems allow passing the result of
 174 .\" .IR valloc ()
 175 .\" to
 176 .\" .IR free (3),
 177 .\" but not to
 178 .\" .IR realloc (3).
 179 POSIX では \fBposix_memalign\fP() によって獲得したメモリは \fBfree\fP(3) を
 180 使って解放することができる必要がある。 いくつかのシステムでは
 181 \fBmemalign\fP() や\fBvalloc\fP() で割り当てられたメモリを再利用する手段が
 182 提供されていない(なぜなら \fBfree\fP(3) に渡すことができるのは
 183 \fBmalloc\fP(3) から受け取ったポインタだけだが、例えば \fBmemalign\fP() は
 184 \fBmalloc\fP(3) を呼び出し、得た値をアラインメントしてしまうからである)。
 185 glibc の実装では、 ここに述べた関数のいずれで獲得したメモリも
 186 \fBfree\fP(3) で再利用することができる。
 187
 188 glibc の \fBmalloc\fP(3) は常に 8 バイトにアラインメントされたメモリアドレスを
 189 返すので、ここで述べた関数が必要になるのは 8 バイトよりも大きなアラインメント
 190 が必要な場合だけである。
 191 .SH 関連項目
 192 \fBbrk\fP(2), \fBgetpagesize\fP(2), \fBfree\fP(3), \fBmalloc\fP(3)
 193 .SH この文書について
 194 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.54 の一部
 195 である。プロジェクトの説明とバグ報告に関する情報は
 196 http://www.kernel.org/doc/man\-pages/ に書かれている。