draft/man2/sendfile.2

   1 .\" This man page is Copyright (C) 1998 Pawel Krawczyk.
   2 .\" Permission is granted to distribute possibly modified copies
   3 .\" of this page provided the header is included verbatim,
   4 .\" and in case of nontrivial modification author and date
   5 .\" of the modification is added to the header.
   6 .\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $
   7 .\" 2000-11-19 bert hubert <ahu@ds9a.nl>: in_fd cannot be socket
   8 .\"
   9 .\" 2004-12-17, mtk
  10 .\"     updated description of in_fd and out_fd for 2.6
  11 .\"     Various wording and formatting changes
  12 .\"
  13 .\" 2005-03-31 Martin Pool <mbp@sourcefrog.net> mmap() improvements
  14 .\"
  15 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  16 .\"         all rights reserved.
  17 .\" Translated 1999-06-26, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\" Updated 2001-02-16, Kentaro Shirakata <argrath@ub32.org>
  19 .\" Updated 2003-09-08, Kentaro Shirakata <argrath@ub32.org>
  20 .\" Updated 2005-03-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  21 .\" Updated 2005-04-17, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  22 .\" Updated 2010-04-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.24
  23 .\"
  24 .\"WORD:        descriptor              ディスクリプタ
  25 .\"WORD:        socket                  ソケット
  26 .\"WORD:        lock                    ロック
  27 .\"
  28 .TH SENDFILE 2 2010-02-15 "Linux" "Linux Programmer's Manual"
  29 .SH 名前
  30 sendfile \- ファイル・ディスクリプタ間でデータを転送する
  31 .SH 書式
  32 .B #include <sys/sendfile.h>
  33 .sp
  34 .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
  35                       offset ", size_t" " count" );
  36 .\"O .\" The below is too ugly. Comments about glibc versions belong
  37 .\"O .\" in the notes, not in the header.
  38 .\" 以下は、あまりにも汚い。 glibc バージョンについてのコメントは
  39 .\" 「ヘッダ」ではなく、「注意」に書いておく。
  40 .\"
  41 .\" .B #include <features.h>
  42 .\" .br
  43 .\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
  44 .\" .br
  45 .\" .B #include <sys/sendfile.h>
  46 .\" .br
  47 .\" #else
  48 .\" .br
  49 .\" .B #include <sys/types.h>
  50 .\" .br
  51 .\" .B /* No system prototype before glibc 2.1. */
  52 .\" .br
  53 .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
  54 .\"                       offset ", size_t" " count" )
  55 .\" .br
  56 .\" .B #endif
  57 .\"
  58 .SH 説明
  59 .\"O .BR sendfile ()
  60 .\"O copies data between one file descriptor and another.
  61 .\"O Because this copying is done within the kernel,
  62 .\"O .BR sendfile ()
  63 .\"O is more efficient than the combination of
  64 .\"O .BR read (2)
  65 .\"O and
  66 .\"O .BR write (2),
  67 .\"O which would require transferring data to and from user space.
  68 .BR sendfile ()
  69 は、あるファイル・ディスクリプタから別の
  70 ファイル・ディスクリプタへのデータのコピーを行う。
  71 このコピーはカーネル内で行われるので、
  72 .BR sendfile ()
  73 は、
  74 .BR read (2)
  75 と
  76 .BR write (2)
  77 を組み合わせるよりも効率がよい。
  78 .BR read (2)
  79 や
  80 .BR write (2)
  81 ではユーザ空間との間でデータの転送が必要となるからである。
  82
  83 .\"O .I in_fd
  84 .\"O should be a file descriptor opened for reading and
  85 .\"O .I out_fd
  86 .\"O should be a descriptor opened for writing.
  87 .I in_fd
  88 は読み込みのためにオープンされたファイル・ディスクリプタ、
  89 .I out_fd
  90 は書き込みのためにオープンされたディスクリプタでなければならない。
  91
  92 .\"O If
  93 .\"O .I offset
  94 .\"O is not NULL, then it points
  95 .\"O to a variable holding the file offset from which
  96 .\"O .BR sendfile ()
  97 .\"O will start reading data from
  98 .\"O .IR in_fd .
  99 .\"O When
 100 .\"O .BR sendfile ()
 101 .\"O returns, this variable
 102 .\"O will be set to the offset of the byte following the last byte that was read.
 103 .I offset
 104 が NULL でない場合、
 105 .I offset
 106 は
 107 .BR sendfile ()
 108 が
 109 .I in_fd
 110 のどこからデータを読み始めるかを示すファイル・オフセットを保持する変数への
 111 ポインタである。
 112 .BR sendfile ()
 113 は復帰する時、この変数に最後に読み込んだバイトの
 114 次のバイトのオフセットを書き込む。
 115 .\"O If
 116 .\"O .I offset
 117 .\"O is not NULL, then
 118 .\"O .BR sendfile ()
 119 .\"O does not modify the current file offset of
 120 .\"O .IR in_fd ;
 121 .\"O otherwise the current file offset is adjusted to reflect
 122 .\"O the number of bytes read from
 123 .\"O .IR in_fd .
 124 .I offset
 125 が NULL でない場合、
 126 .BR sendfile ()
 127 は
 128 .I in_fd
 129 のファイル・オフセットの現在値を変更しない。
 130 NULL の場合は、ファイル・オフセットの現在値を
 131 .I in_fd
 132 から読み込んだバイト数を反映した位置に調整する。
 133
 134 .\"O If
 135 .\"O .I offset
 136 .\"O is NULL, then data will be read from
 137 .\"O .IR in_fd
 138 .\"O starting at the current file offset,
 139 .\"O and the file offset will be updated by the call.
 140 .I offset
 141 が NULL の場合、データは
 142 .I in_fd
 143 の現在のファイル・オフセットから読み出され、
 144 ファイル・オフセットはこの呼び出しで更新される。
 145
 146 .\"O .I count
 147 .\"O is the number of bytes to copy between the file descriptors.
 148 .I count
 149 は、ファイル・ディスクリプタ間でコピーするバイト数である。
 150
 151 .\"O Presently (Linux 2.6.9):
 152 .\"O .IR in_fd ,
 153 .\"O must correspond to a file which supports
 154 .\"O .BR mmap (2)-like
 155 .\"O operations
 156 .\"O (i.e., it cannot be a socket);
 157 .\"O and
 158 .\"O .I out_fd
 159 .\"O must refer to a socket.
 160 今のところ (Linux 2.6.9 では)、
 161 .I in_fd
 162 は
 163 .BR mmap (2)
 164 風の操作ができるファイルを指していなければならない
 165 (ソケットを指してはならない)。また、
 166 .I out_fd
 167 はソケットを指していなければならない。
 168
 169 .\"O Applications may wish to fall back to
 170 .\"O .BR read (2)/ write (2)
 171 .\"O in the case where
 172 .\"O .BR sendfile ()
 173 .\"O fails with
 174 .\"O .B EINVAL
 175 .\"O or
 176 .\"O .BR ENOSYS .
 177 .BR sendfile ()
 178 が
 179 .B EINVAL
 180 や
 181 .B ENOSYS
 182 で失敗するような場合は、
 183 アプリケーションは
 184 .BR read (2)/ write (2)
 185 に戻すことを考えてもよいかもしれない。
 186 .\"O .SH "RETURN VALUE"
 187 .SH 返り値
 188 .\"O If the transfer was successful, the number of bytes written to
 189 .\"O .I out_fd
 190 .\"O is returned.
 191 .\"O On error, \-1 is returned, and
 192 .\"O .I errno
 193 .\"O is set appropriately.
 194 転送に成功した場合、
 195 .I out_fd
 196 に書き込まれたバイト数を返す。エラーの場合、\-1 を返し、
 197 .I errno
 198 に適切な値を設定する。
 199 .\"O .SH ERRORS
 200 .SH エラー
 201 .TP
 202 .B EAGAIN
 203 .\"O Nonblocking I/O has been selected using
 204 .\"O .B O_NONBLOCK
 205 .\"O and the write would block.
 206 .B O_NONBLOCK
 207 を用いて非ブロック I/O が選択されたが、書き込みがブロックされた。
 208 .TP
 209 .B EBADF
 210 .\"O The input file was not opened for reading or the output file
 211 .\"O was not opened for writing.
 212 入力ファイルが読み込みのためにオープンされていないか、
 213 出力ファイルが書き込みのためにオープンされていない。
 214 .TP
 215 .B EFAULT
 216 .\"O Bad address.
 217 アドレスがおかしい。
 218 .TP
 219 .B EINVAL
 220 .\"O Descriptor is not valid or locked, or an
 221 .\"O .BR mmap (2)-like
 222 .\"O operation is not available for
 223 .\"O .IR in_fd .
 224 ディスクリプタが有効でないか、ロックされている。もしくは
 225 .BR mmap (2)
 226 風の操作が
 227 .I in_fd
 228 では利用できない。
 229 .TP
 230 .B EIO
 231 .\"O Unspecified error while reading from
 232 .\"O .IR in_fd .
 233 .I in_fd
 234 から読み込んでいるうちに予期しないエラーが起こった。
 235 .TP
 236 .B ENOMEM
 237 .\"O Insufficient memory to read from
 238 .\"O .IR in_fd .
 239 .I in_fd
 240 から読み込むための十分なメモリがない。
 241 .\"O .SH VERSIONS
 242 .SH バージョン
 243 .\"O .B sendfile
 244 .\"O is a new feature in Linux 2.2.
 245 .B sendfile
 246 は Linux 2.2 の新しい機能である。
 247 .\"O The include file
 248 .\"O .I <sys/sendfile.h>
 249 .\"O is present since glibc 2.1.
 250 インクルードファイル
 251 .I <sys/sendfile.h>
 252 は glibc 2.1 から存在している。
 253 .\"O .SH "CONFORMING TO"
 254 .SH 準拠
 255 .\"O Not specified in POSIX.1-2001, or other standards.
 256 POSIX.1-2001 や他の標準では規定されていない。
 257
 258 .\"O Other UNIX systems implement
 259 .\"O .BR sendfile ()
 260 .\"O with different semantics and prototypes.
 261 .\"O It should not be used in portable programs.
 262 他の UNIX システムでは、異なった方式やプロトタイプで
 263 .BR sendfile ()
 264 を実装している。移植性を考慮したプログラムでは使用すべきではない。
 265 .\"O .SH NOTES
 266 .SH 注意
 267 .\"O If you plan to use
 268 .\"O .BR sendfile ()
 269 .\"O for sending files to a TCP socket, but need
 270 .\"O to send some header data in front of the file contents, you will find
 271 .\"O it useful to employ the
 272 .\"O .B TCP_CORK
 273 .\"O option, described in
 274 .\"O .BR tcp (7),
 275 .\"O to minimize the number of packets and to tune performance.
 276 .BR sendfile ()
 277 を使って TCP ソケットにファイルを送ろうとしていて、
 278 ファイルの内容の前にヘッダ・データを付け加える必要がある場合は、
 279 パケット数を最小にして性能を上げるために
 280 .BR tcp (7)
 281 に記述されている
 282 .B TCP_CORK
 283 オプションを使うといいだろう。
 284
 285 .\"O In Linux 2.4 and earlier,
 286 .\"O .I out_fd
 287 .\"O could refer to a regular file, and
 288 .\"O .BR sendfile ()
 289 .\"O changed the current offset of that file.
 290 Linux 2.4 とそれ以前のバージョンでは、
 291 .I out_fd
 292 は通常のファイルを参照でき、
 293 .BR sendfile ()
 294 はそのファイルのオフセットの現在値を変更していた。
 295 .\"O .SH SEE ALSO
 296 .SH 関連項目
 297 .BR mmap (2),
 298 .BR open (2),
 299 .BR socket (2),
 300 .BR splice (2)