release/man2/posix_fadvise.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright 2003 Abhijit Menon-Sen <ams@wiw.org>
   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 .\"
  24 .\" 2005-04-08 mtk, noted kernel version and added BUGS
  25 .\"
  26 .\" Japanese Version Copyright (c) 2004-2007 Yuichi SATO
  27 .\"         all rights reserved.
  28 .\" Translated Sun Jun 20 16:23:17 JST 2004
  29 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v1.66
  30 .\" Updated & Modified Fri Apr 22 03:05:51 JST 2005 by Yuichi SATO, LDP v2.02
  31 .\" Updated & Modified Thu Jan  4 23:55:18 JST 2007 by Yuichi SATO, LDP v2.43
  32 .\"
  33 .TH POSIX_FADVISE 2 2003-02-14 "Linux" "Linux Programmer's Manual"
  34 .SH 名前
  35 posix_fadvise \- ファイルデータのアクセスパターンをあらかじめ宣言する
  36 .SH 書式
  37 .nf
  38 .B #define _XOPEN_SOURCE 600
  39 .B #include <fcntl.h>
  40 .sp
  41 .BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \
  42 ", int " advice ");"
  43 .fi
  44 .SH 説明
  45 プログラムは、将来特定のパターンでファイルデータに
  46 アクセスする意思を伝えるために
  47 .BR posix_fadvise ()
  48 を使うことができる。
  49 これにより、カーネルが適切な最適化を実行することが可能になる。
  50
  51 \fIadvice\fP は  \fIfd\fP が参照しているファイルの
  52 \fIoffset\fP から始まる \fIlen\fP バイトの範囲内
  53 (\fIlen\fP が 0 の場合はファイルの終りまで) の
  54 (必ずしも存在しない) 領域に適用される。
  55 アドバイスは義務づけではない。
  56 アドバイスは単にアプリケーションのために可能性を構成するだけである。
  57
  58 \fIadvice\fP に許される値には、以下のものが含まれる:
  59 .TP
  60 .B POSIX_FADV_NORMAL
  61 指定されたデータのアクセスパターンを指示するアドバイスを
  62 アプリケーションが何も持っていないことを示す。
  63 オープンされたファイルにアドバイスが指定されない場合、
  64 これがデフォルトで仮定される。
  65 .TP
  66 .B POSIX_FADV_SEQUENTIAL
  67 アプリケーションは指定されたデータがシーケンシャルに
  68 (大きなオフセットの前に小さなオフセットのデータを読むように)
  69 アクセスされることを期待する。
  70 .TP
  71 .B POSIX_FADV_RANDOM
  72 指定されたデータがランダムな順番でアクセスされる。
  73 .TP
  74 .B POSIX_FADV_NOREUSE
  75 指定されたデータは 1 度しかアクセスされない。
  76 .TP
  77 .B POSIX_FADV_WILLNEED
  78 指定されたデータは近い将来アクセスされる。
  79 .TP
  80 .B POSIX_FADV_DONTNEED
  81 指定されたデータは近い将来アクセスされない。
  82 .SH 返り値
  83 成功した場合は 0 が返される。
  84 失敗した場合はエラー番号が返される。
  85 .SH エラー
  86 .TP
  87 .B EBADF
  88 \fIfd\fP 引き数が有効なファイルディスクリプタでない。
  89 .TP
  90 .B EINVAL
  91 無効な値が \fIadvice\fP に指定された。
  92 .TP
  93 .B ESPIPE
  94 指定されたファイルディスクリプタがパイプまたは FIFO を参照している
  95 (この場合、Linux は実際には
  96 .B EINVAL
  97 を返す)。
  98 .SH バージョン
  99 .BR posix_fadvise ()
 100 はカーネル 2.5.60 で登場した。
 101 .\" 実際には fadvise64() として登場した。-- MTK
 102 glibc でのサポートは glibc バージョン 2.2 以降で行われている。
 103 .SH 準拠
 104 POSIX.1-2001.
 105 .I len
 106 引き数の型が POSIX.1-2003 TC1 において
 107 .I size_t
 108 から
 109 .I off_t
 110 に変更された点に注意すること。
 111 .SH 注意
 112 Linux では、\fBPOSIX_FADV_NORMAL\fP はバッキングデバイスの
 113 デフォルトサイズに先読み (readahead) ウインドウを設定する。
 114 \fBPOSIX_FADV_SEQUENTIAL\fP はこのサイズを 2 倍し、
 115 \fBPOSIX_FADV_RANDOM\fP は先読みを全く無効にする。
 116 これらの変更はファイル全体に影響し、指定された領域のみに影響するわけではない
 117 (しかし同じファイルに対する他のオープンファイルハンドルは影響を受けない)。
 118
 119 \fBPOSIX_FADV_WILLNEED\fP は、
 120 ページキャッシュに指定領域のブロックされない読み込みを開始する。
 121 読み込まれるデータの総量は、
 122 仮想メモリの負荷に依ってカーネルが減らすかもしれない
 123 (数メガバイトであれば通常は全く十分であり、
 124 それより多くてもめったに役に立たない)。
 125
 126 2.6.18 より前のカーネルでは、\fBPOSIX_FADV_NOREUSE\fP は
 127 \fBPOSIX_FADV_WILLNEED\fP と同じ意味であった。
 128 これは多分バグであった。
 129 カーネル 2.6.18 以降では、このフラグは何も行わない。
 130
 131 \fBPOSIX_FADV_DONTNEED\fP は指定された領域に関連付けられた
 132 キャッシュページを解放しようとする。
 133 例えば、これは大きなファイルをストリーミングするときに役立つ。
 134 プログラムは、使用済みのキャッシュされたデータを解放するように、
 135 定期的にカーネルに要求するかもしれない。
 136 そうすることにより、さらに有効なキャッシュされたページが、
 137 代わりに破棄されることはない。
 138
 139 まだ書き出されていないページは影響を受けないので、
 140 そのページの解放が保証されることをアプリケーションが望んでいるなら、
 141 最初に
 142 .BR fsync (2)
 143 または
 144 .BR fdatasync (2)
 145 を呼ぶべきである。
 146 .SH バグ
 147 2.6.6 より前のカーネルでは、
 148 .I len
 149 に 0 が指定された場合、
 150 「ファイルの終りまでの全てのバイト」という意味ではなく、
 151 文字通り「0 バイト」として解釈されていた。
 152 .SH 関連項目
 153 .BR readahead (2),
 154 .BR posix_fallocate (3),
 155 .BR posix_madvise (3)
 156 .\" FIXME . Write a posix_fadvise(3) page.