名前

       posix_memalign, aligned_alloc, memalign, valloc, pvalloc - アラインメント されたメモリーの割り当てを行う

書式

       #include <stdlib.h>

       int posix_memalign(void **memptr, size_t alignment, size_t size);
       void *aligned_alloc(size_t alignment, size_t size);
       void *valloc(size_t size);

       #include <malloc.h>

       void *memalign(size_t alignment, size_t size);
       void *pvalloc(size_t size);

   glibc 向けの機能検査マクロの要件 (feature_test_macros(7)  参照):

       posix_memalign(): _POSIX_C_SOURCE >= 200112L

       aligned_alloc(): _ISOC11_SOURCE

       valloc():
           glibc 2.12 以降:
               (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
                   || /* glibc 2.19 以降: */ _DEFAULT_SOURCE
                   || /* glibc 2.19 以前: */ _SVID_SOURCE || _BSD_SOURCE
           glibc 2.12 より前:
               _BSD_SOURCE || _XOPEN_SOURCE >= 500
               ((非標準の)  ヘッダーファイル  <malloc.h>  も valloc() の宣言も公開する。機能検査マクロは不要であ
               る。

説明

       The function posix_memalign()  allocates size bytes and places the address of  the  allocated  memory  in
       *memptr.   The  address of the allocated memory will be a multiple of alignment, which must be a power of
       two and a multiple of sizeof(void *).  This address can later be successfully passed to free(3).  If size
       is 0, then the value placed in *memptr is either NULL or a unique pointer value.

       廃止された関数である memalign() は、 size  バイトのメモリーを割り当て、  割り当てられたメモリーへのポイン
       ターを返す。  メモリーのアドレスは alignment の倍数になっているはずである。 alignment は 2 のべき乗でなけ
       ればならない。

       関数 aligned_alloc() は memalign() と同じだが、size が alignment の倍数でなければならないという追加の制限
       がある点が異なる。

       廃止された関数である valloc()  は size バイトのメモリーを割り当て、割り当てられたメモリーへのポインターを
       返す。               メモリーのアドレスはページサイズの倍数になっているはずである。                これは
       memalign(sysconf(_SC_PAGESIZE),size) と等価である。

       廃止された関数  pvalloc() は valloc() と同様だが、 割り当てられるサイズがシステムのページサイズの倍数に切
       り上げられる。

       これらの関数はいずれもメモリーのゼロクリアを行わない。

返り値

       aligned_alloc(), memalign(), valloc(), and pvalloc()   return  a  pointer  to  the  allocated  memory  on
       success.  On error, NULL is returned, and errno is set to indicate the cause of the error.

       posix_memalign()   returns  zero  on  success,  or  one of the error values listed in the next section on
       failure.  The value of errno is not set.  On Linux (and other systems), posix_memalign()  does not modify
       memptr on failure.  A requirement standardizing this behavior was added in POSIX.1-2008 TC2.

エラー

       EINVAL alignment 引数が 2 のべき乗でなかったか、 sizeof(void *) の倍数でなかった。

       ENOMEM 割り当て要求を満たすのに十分なメモリーがなかった。

バージョン

       関数 memalign(), valloc(), pvalloc() は少なくとも glibc 2.0 以降で使用可能である。

       関数 aligned_alloc() は glibc バージョン 2.16 で追加された。

       関数 posix_fallocate() は glibc 2.1.91 以降で利用可能である。

属性

       この節で使用されている用語の説明については、 attributes(7) を参照。
       ┌──────────────────┬───────────────┬────────────────┐
       │ インターフェース │ 属性          │ 値             │
       ├──────────────────┼───────────────┼────────────────┤
       │ aligned_alloc(), │ Thread safety │ MT-Safe        │
       │ memalign(),      │               │                │
       │ posix_memalign() │               │                │
       ├──────────────────┼───────────────┼────────────────┤
       │ valloc(),        │ Thread safety │ MT-Unsafe init │
       │ pvalloc()        │               │                │
       └──────────────────┴───────────────┴────────────────┘

準拠

       関数 valloc() は 3.0BSD で登場した。4.3BSD では廃止されたと記載されており、 SUSv2  では過去の名残だと記載
       されている。 POSIX.1 には存在しない。

       関数 pvalloc() は GNU による拡張である。

       関数 memalign() は SunOS 4.1.3 で登場したが、4.4BSD にはない。

       関数 posix_memalign() は POSIX.1d に由来し、 POSIX.1-2001 と POSIX.1-2008 で規定されている。

       関数 aligned_alloc() は C11 標準で規定されている。

   ヘッダー
       posix_memalign()  の宣言を <stdlib.h> で行うことに関しては、 皆の意見が一致している。

       いくつかのシステムでは、 memalign()  は <malloc.h> ではなく <stdlib.h> で宣言されている。

       SUSv2  によると、 valloc() は <stdlib.h> で宣言される。 glibc では <malloc.h> で宣言されており、 さらに適
       切な機能検査マクロが定義された場合には <stdlib.h> でも宣言される(上記を参照)。

注意

       多くのシステムでは、アラインメントに関して制限がある。例えば、 ブロックデバイスに対するダイレクト I/O  に
       使用するバッファーには  アラインメントに関する制限がある。 POSIX では、どんなアラインメントが必要かを知る
       ために pathconf(path,_PC_REC_XFER_ALIGN) コールを規定している。ここで posix_memalign() を使うと、この必要
       条件を満たすことができる。

       posix_memalign()  は  alignment  が上で詳細に述べた必要条件を満たすか  どうかを確かめる。  memalign()  は
       alignment 引数が正しいかどうかの 確認を行わないかもしれない。

       POSIX  では posix_memalign() によって獲得したメモリーは free(3) を 使って解放することができる必要がある。
       いくつかのシステムでは memalign()  やvalloc()  で割り当てられたメモリーを再利用する手段が  提供されていな
       い(なぜなら  free(3) に渡すことができるのは malloc(3) から受け取ったポインターだけだが、例えば memalign()
       は malloc(3) を呼び出し、得た値をアラインメントしてしまうからである)。 glibc の実装では、  ここに述べた関
       数のいずれで獲得したメモリーも free(3) で再利用することができる。

       glibc の malloc(3) は常に 8 バイトにアラインメントされたメモリーアドレスを 返すので、ここで述べた関数が必
       要になるのは 8 バイトよりも大きなアラインメント が必要な場合だけである。

関連項目

       brk(2), getpagesize(2), free(3), malloc(3)

この文書について

       この  man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告
       に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。

GNU                                                2020-12-21                                  POSIX_MEMALIGN(3)