draft/man2/posix_fadvise.2

   1 .\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   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_END
  24 .\"
  25 .\" 2005-04-08 mtk, noted kernel version and added BUGS
  26 .\" 2010-10-09, mtk, document arm_fadvise64_64()
  27 .\"
  28 .\"*******************************************************************
  29 .\"
  30 .\" This file was generated with po4a. Translate the source file.
  31 .\"
  32 .\"*******************************************************************
  33 .\"
  34 .\" Japanese Version Copyright (c) 2004-2007 Yuichi SATO
  35 .\"         all rights reserved.
  36 .\" Translated Sun Jun 20 16:23:17 JST 2004
  37 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v1.66
  38 .\" Updated & Modified Fri Apr 22 03:05:51 JST 2005 by Yuichi SATO, LDP v2.02
  39 .\" Updated & Modified Thu Jan  4 23:55:18 JST 2007 by Yuichi SATO, LDP v2.43
  40 .\" Updated 2012-05-31, Akihiro MOTOKI <amotoki@gmail.com>
  41 .\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
  42 .\"
  43 .TH POSIX_FADVISE 2 2014\-12\-31 Linux "Linux Programmer's Manual"
  44 .SH 名前
  45 posix_fadvise \- ファイルデータのアクセスパターンをあらかじめ宣言する
  46 .SH 書式
  47 .nf
  48 \fB#include <fcntl.h>\fP
  49 .sp
  50 \fBint posix_fadvise(int \fP\fIfd\fP\fB, off_t \fP\fIoffset\fP\fB, off_t \fP\fIlen\fP\fB, int \fP\fIadvice\fP\fB);\fP
  51 .fi
  52 .sp
  53 .ad l
  54 .in -4n
  55 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  56 .in
  57 .sp
  58 \fBposix_fadvise\fP():
  59 .RS 4
  60 _XOPEN_SOURCE\ >=\ 600 || _POSIX_C_SOURCE\ >=\ 200112L
  61 .RE
  62 .ad
  63 .SH 説明
  64 プログラムは、将来特定のパターンでファイルデータに アクセスする意思を伝えるために \fBposix_fadvise\fP()  を使うことができる。
  65 これにより、カーネルが適切な最適化を実行することが可能になる。
  66
  67 \fIadvice\fP は \fIfd\fP が参照しているファイルの \fIoffset\fP から始まる \fIlen\fP バイ
  68 トの範囲内 (\fIlen\fP が 0 の場合はファイルの終りまで) の (必ずしも存在しない)
  69 領域に適用される。 \fIadvice\fP は義務づけではない。 \fIadvice\fP は単にアプリケー
  70 ションのために可能性を構成するだけである。
  71
  72 \fIadvice\fP に許される値には、以下のものが含まれる:
  73 .TP
  74 \fBPOSIX_FADV_NORMAL\fP
  75 指定されたデータのアクセスパターンを指示するアドバイスを アプリケーションが何も持っていないことを示す。
  76 オープンされたファイルにアドバイスが指定されない場合、 これがデフォルトで仮定される。
  77 .TP
  78 \fBPOSIX_FADV_SEQUENTIAL\fP
  79 アプリケーションは指定されたデータがシーケンシャルに (大きなオフセットの前に小さなオフセットのデータを読むように)  アクセスされることを期待する。
  80 .TP
  81 \fBPOSIX_FADV_RANDOM\fP
  82 指定されたデータがランダムな順番でアクセスされる。
  83 .TP
  84 \fBPOSIX_FADV_NOREUSE\fP
  85 指定されたデータは 1 度しかアクセスされない。
  86 .TP
  87 \fBPOSIX_FADV_WILLNEED\fP
  88 指定されたデータは近い将来アクセスされる。
  89 .TP
  90 \fBPOSIX_FADV_DONTNEED\fP
  91 指定されたデータは近い将来アクセスされない。
  92 .SH 返り値
  93 成功した場合は 0 が返される。 失敗した場合はエラー番号が返される。
  94 .SH エラー
  95 .TP
  96 \fBEBADF\fP
  97 \fIfd\fP 引き数が有効なファイルディスクリプタでない。
  98 .TP
  99 \fBEINVAL\fP
 100 無効な値が \fIadvice\fP に指定された。
 101 .TP
 102 \fBESPIPE\fP
 103 .\" commit 87ba81dba431232548ce29d5d224115d0c2355ac
 104 指定されたファイルディスクリプタがパイプまたは FIFO を参照している (\fBESPIPE\fP は POSIX で規定されているエラーだが、 バージョン
 105 2.16 より前のカーネルでは、 この場合に \fBEINVAL\fP を返していた。)
 106 .SH バージョン
 107 .\" of fadvise64_64()
 108 カーネルによるサポートは Linux 2.5.60 で最初に登場し、
 109 対応するシステムコールは \fBfadvise64\fP() という名前である。
 110 ライブラリによるサポートは glibc バージョン 2.2 以降で提供されており、
 111 ラッパー関数は \fBposix_fadvise\fP() という名前である。
 112
 113 .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
 114 Linux 3.18 以降では、対応するシステムコールのサポートは任意となり、利用できるかはカーネルが
 115 \fBCONFIG_ADVISE_SYSCALLS\fP オプションを有効にしてコンパイルされているかに依存する。
 116 .SH 準拠
 117 POSIX.1\-2001.  \fIlen\fP 引き数の型が POSIX.1\-2003 TC1 において \fIsize_t\fP から \fIoff_t\fP
 118 に変更された点に注意すること。
 119 .SH 注意
 120 Linux では、\fBPOSIX_FADV_NORMAL\fP はバッキングデバイスの デフォルトサイズに先読み (readahead)
 121 ウインドウを設定する。 \fBPOSIX_FADV_SEQUENTIAL\fP はこのサイズを 2 倍し、 \fBPOSIX_FADV_RANDOM\fP
 122 は先読みを全く無効にする。 これらの変更はファイル全体に影響し、指定された領域のみに影響するわけではない
 123 (しかし同じファイルに対する他のオープンファイルハンドルは影響を受けない)。
 124
 125 \fBPOSIX_FADV_WILLNEED\fP は、 ページキャッシュに指定領域のブロックされない読み込みを開始する。 読み込まれるデータの総量は、
 126 仮想メモリの負荷に依ってカーネルが減らすかもしれない (数メガバイトであれば通常は全く十分であり、 それより多くてもめったに役に立たない)。
 127
 128 2.6.18 より前のカーネルでは、\fBPOSIX_FADV_NOREUSE\fP は \fBPOSIX_FADV_WILLNEED\fP と同じ意味であった。
 129 これは多分バグであった。 カーネル 2.6.18 以降では、このフラグは何も行わない。
 130
 131 \fBPOSIX_FADV_DONTNEED\fP は指定された領域に関連付けられた キャッシュページを解放しようとする。
 132 例えば、これは大きなファイルをストリーミングするときに役立つ。 プログラムは、使用済みのキャッシュされたデータを解放するように、
 133 定期的にカーネルに要求するかもしれない。 そうすることにより、さらに有効なキャッシュされたページが、 代わりに破棄されることはない。
 134
 135 ページの一部分の破棄要求は無視される。 不要なデータを破棄するよりも必要なデータを保持する方がよい。
 136 アプリケーションがデータを破棄した方がよいと思う場合は、 \fIoffset\fP と \fIlen\fP がページ境界に合っていなければならない。
 137
 138 まだ書き出されていないページは影響を受けないので、 そのページの解放が保証されることをアプリケーションが望んでいるなら、 最初に \fBfsync\fP(2)
 139 または \fBfdatasync\fP(2)  を呼ぶべきである。
 140 .SS アーキテクチャ固有の派生バージョン
 141 いくつかのアーキテクチャでは、 64 ビットの引き数は適切なレジスタの組に割り当てる必要がある (\fBsyscall\fP(2) 参照)。
 142 このようなアーキテクチャでは、 「書式」に書かれている  \fBposix_fadvise\fP() の呼び出しシグネチャーで、 引き数 \fIfd\fP と
 143 \fIoffset\fP の間のパディング (詰めもの) でレジスタが一つ消費されてしまう。 そのため、
 144 これらのアーキテクチャでは引き数が適切な順序になった別のシステムコールが定義されているが、 それ以外は \fBposix_fadvise\fP()
 145 と全く同じである。
 146
 147 例えば、 Linux 2.6.14 以降では、 ARM には以下のシステムコールが存在する。
 148 .PP
 149 .in +4n
 150 .nf
 151 \fBlong arm_fadvise64_64(int \fP\fIfd\fP\fB, int \fP\fIadvice\fP\fB,\fP
 152 \fB                      loff_t \fP\fIoffset\fP\fB, loff_t \fP\fIlen\fP\fB);\fP
 153 .fi
 154 .in
 155 .PP
 156 通常、 glibc の \fBposix_fadvise\fP() ラッパー関数により、 これらのアーキテクチャ固有の詳細はアプリケーションには見えない。
 157 glibc のラッパー関数では、適切なアーキテクチャ固有のシステムコールが呼び出される。
 158 .SH バグ
 159 2.6.6 より前のカーネルでは、 \fIlen\fP に 0 が指定された場合、 「ファイルの終りまでの全てのバイト」という意味ではなく、 文字通り「0
 160 バイト」として解釈されていた。
 161 .SH 関連項目
 162 .\" FIXME . Write a posix_fadvise(3) page.
 163 \fBreadahead\fP(2), \fBsync_file_range\fP(2), \fBposix_fallocate\fP(3),
 164 \fBposix_madvise\fP(3)
 165 .SH この文書について
 166 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
 167 である。プロジェクトの説明とバグ報告に関する情報は
 168 http://www.kernel.org/doc/man\-pages/ に書かれている。