release/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 .\" 以下は、あまりにも汚い。 glibc バージョンについてのコメントは
  37 .\" 「ヘッダ」ではなく、「注意」に書いておく。
  38 .\"
  39 .\" .B #include <features.h>
  40 .\" .br
  41 .\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2
  42 .\" .br
  43 .\" .B #include <sys/sendfile.h>
  44 .\" .br
  45 .\" #else
  46 .\" .br
  47 .\" .B #include <sys/types.h>
  48 .\" .br
  49 .\" .B /* No system prototype before glibc 2.1. */
  50 .\" .br
  51 .\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \
  52 .\"                       offset ", size_t" " count" )
  53 .\" .br
  54 .\" .B #endif
  55 .\"
  56 .SH 説明
  57 .BR sendfile ()
  58 は、あるファイル・ディスクリプタから別の
  59 ファイル・ディスクリプタへのデータのコピーを行う。
  60 このコピーはカーネル内で行われるので、
  61 .BR sendfile ()
  62 は、
  63 .BR read (2)
  64 と
  65 .BR write (2)
  66 を組み合わせるよりも効率がよい。
  67 .BR read (2)
  68 や
  69 .BR write (2)
  70 ではユーザ空間との間でデータの転送が必要となるからである。
  71
  72 .I in_fd
  73 は読み込みのためにオープンされたファイル・ディスクリプタ、
  74 .I out_fd
  75 は書き込みのためにオープンされたディスクリプタでなければならない。
  76
  77 .I offset
  78 が NULL でない場合、
  79 .I offset
  80 は
  81 .BR sendfile ()
  82 が
  83 .I in_fd
  84 のどこからデータを読み始めるかを示すファイル・オフセットを保持する変数への
  85 ポインタである。
  86 .BR sendfile ()
  87 は復帰する時、この変数に最後に読み込んだバイトの
  88 次のバイトのオフセットを書き込む。
  89 .I offset
  90 が NULL でない場合、
  91 .BR sendfile ()
  92 は
  93 .I in_fd
  94 のファイル・オフセットの現在値を変更しない。
  95 NULL の場合は、ファイル・オフセットの現在値を
  96 .I in_fd
  97 から読み込んだバイト数を反映した位置に調整する。
  98
  99 .I offset
 100 が NULL の場合、データは
 101 .I in_fd
 102 の現在のファイル・オフセットから読み出され、
 103 ファイル・オフセットはこの呼び出しで更新される。
 104
 105 .I count
 106 は、ファイル・ディスクリプタ間でコピーするバイト数である。
 107
 108 今のところ (Linux 2.6.9 では)、
 109 .I in_fd
 110 は
 111 .BR mmap (2)
 112 風の操作ができるファイルを指していなければならない
 113 (ソケットを指してはならない)。また、
 114 .I out_fd
 115 はソケットを指していなければならない。
 116
 117 .BR sendfile ()
 118 が
 119 .B EINVAL
 120 や
 121 .B ENOSYS
 122 で失敗するような場合は、
 123 アプリケーションは
 124 .BR read (2)/ write (2)
 125 に戻すことを考えてもよいかもしれない。
 126 .SH 返り値
 127 転送に成功した場合、
 128 .I out_fd
 129 に書き込まれたバイト数を返す。エラーの場合、\-1 を返し、
 130 .I errno
 131 に適切な値を設定する。
 132 .SH エラー
 133 .TP
 134 .B EAGAIN
 135 .B O_NONBLOCK
 136 を用いて非ブロック I/O が選択されたが、書き込みがブロックされた。
 137 .TP
 138 .B EBADF
 139 入力ファイルが読み込みのためにオープンされていないか、
 140 出力ファイルが書き込みのためにオープンされていない。
 141 .TP
 142 .B EFAULT
 143 アドレスがおかしい。
 144 .TP
 145 .B EINVAL
 146 ディスクリプタが有効でないか、ロックされている。もしくは
 147 .BR mmap (2)
 148 風の操作が
 149 .I in_fd
 150 では利用できない。
 151 .TP
 152 .B EIO
 153 .I in_fd
 154 から読み込んでいるうちに予期しないエラーが起こった。
 155 .TP
 156 .B ENOMEM
 157 .I in_fd
 158 から読み込むための十分なメモリがない。
 159 .SH バージョン
 160 .B sendfile
 161 は Linux 2.2 の新しい機能である。
 162 インクルードファイル
 163 .I <sys/sendfile.h>
 164 は glibc 2.1 から存在している。
 165 .SH 準拠
 166 POSIX.1-2001 や他の標準では規定されていない。
 167
 168 他の UNIX システムでは、異なった方式やプロトタイプで
 169 .BR sendfile ()
 170 を実装している。移植性を考慮したプログラムでは使用すべきではない。
 171 .SH 注意
 172 .BR sendfile ()
 173 を使って TCP ソケットにファイルを送ろうとしていて、
 174 ファイルの内容の前にヘッダ・データを付け加える必要がある場合は、
 175 パケット数を最小にして性能を上げるために
 176 .BR tcp (7)
 177 に記述されている
 178 .B TCP_CORK
 179 オプションを使うといいだろう。
 180
 181 Linux 2.4 とそれ以前のバージョンでは、
 182 .I out_fd
 183 は通常のファイルを参照でき、
 184 .BR sendfile ()
 185 はそのファイルのオフセットの現在値を変更していた。
 186 .SH 関連項目
 187 .BR mmap (2),
 188 .BR open (2),
 189 .BR socket (2),
 190 .BR splice (2)