日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
SENDFILE(2) FreeBSD システムコールマニュアル SENDFILE(2) 名称 sendfile -- ファイルをソケットに送信する ライブラリ 標準 C ライブラリ (libc, -lc) 書式 #include <sys/types.h> #include <sys/socket.h> #include <sys/uio.h> int sendfile(int fd, int s, off_t offset, size_t nbytes, struct sf_hdtr *hdtr, off_t *sbytes, int flags); 解説 sendfile() システムコールは、記述子 fd によって指定された通常のファイルま たは共用メモリオブジェクトを記述子 s によって指定されたストリームソケット に送信します。 offset 引数は、ファイルの始まるところを指定します。offset がファイルの終 りを超えていた場合は、システムは、以下に説明されるように成功を返して、0 バイトを送信したと報告します。nbytes 引数は、ファイルのどのくらいバイトが 送信されるべきかを指定し、0 は、ファイルの終わりに到達するまで、送信する という特別な意味があります。 次の構造がある struct sf_hdtr へのポインタを指定することによってファイル データの前と後にオプションのヘッダおよびトレーラを送信することができます: struct sf_hdtr { struct iovec *headers; /* ヘッダ iovecs へのポインタ */ int hdr_cnt; /* ヘッダ iovecs の数 */ struct iovec *trailers; /* トレーラ iovecs へのポインタ */ int trl_cnt; /* トレーラ iovecs の数 */ }; headers と trailers のポインタは、NULL でないなら、struct iovec 構造体の 配列を指します。iovec 構造体に関する情報については、writev() システムコー ルを参照してください。これらの配列の iovecs の数は、hdr_cnt と trl_cnt に よって指定されます。 NULL でないなら、システムは、ソケットで送信されたバイトの合計数を sbytes によって指された変数に書き込むます。 flags 引数の最下位 16 ビットは、これらの値のビットマップです: SF_NODISKIO このフラグによって、sendfile は、ビジーページに 遭遇するとき、ブロックの代わりに EBUSY を返しま す。いくつかの他のプロセスがファイルの同じ領域で 現在、動作しているなら、このまれな状況が起こるか もしれません。それは、短い期間の後に、操作をリト ライするように助言されます。 古い FreeBSD バージョンで、SF_NODISKIO は、少し 異なった観念があることに注意してください。フラグ は、無効の (キャッシュされない) ページに遭遇する 場合に、I/O 操作を実行するために sendfile を防止 します、したがって、I/O でブロックを避けます。 ffs(7) ファイルシステムからの FreeBSD 11.0 sendfile 送信ファイルで開始することは、I/O でブ ロックしないので、(「実装に関する注」を参照) 条 件は、もはや適用しません。しかしながら、アプリ ケーションが古い FreeBSD バージョンで、例えば、 aio_read(2), read(2) または異なるコンテキストの sendfile、同じアクションを実行する EBUSY で、 SF_NODISKIO を利用するなら、それは、安全です。 SF_NOCACHE ソケットに送信されたデータは、仮想メモリシステム によってキャッシュされず、空きページのプールに直 接解放されます。 SF_SYNC sendfile は、その後の修正を安全にして、ネット ワークスタックがもはやファイルの VM ページを参照 しなくなるまで、スリープします。これは、データが 実際に、送信されたことを保証しないことに注意して ください。 SF_USER_READAHEAD sendfile は、データを送信するとき、readahead (先 読み) を行うために、いくつかの内部の発見的手法が あります。このフラグによって、sendfile は、あら ゆる発見的手法で計算された readahead (先読み) を 上書きし、アプリケーションの指定された readahead (先読み) を正確に使用することを強制します。 readahead (先読み) に関する詳細については、 「READAHEAD の設定」を参照してください。 非ブロッキング I/O のためにマークされたソケットを使用するとき、sendfile() は、要求されるより少ないバイトを送信するかもしれません。この場合に、成功 して書き込まれたバイトの数は、(指定されたなら) *sbytes に返され、エラー EAGAIN が、返されます。 READAHEAD の設定 sendfile は、readahead を行うために、要求サイズとファイルシステムのレイア ウトに基づいて内部の発見的手法を使用します。さらに、アプリケーションは、 特別な readahead (先読み) を要求します。flags の最上位 16 ビットは、 sendfile がファイルを読み込むとき、先読みするページの量を指定します。マク ロ SF_FLAGS() は、先読みの量とフラグを組み合わせるために提供されます。例 は、16 ページと SF_NOCACHE フラグの先読みの指定を表示します: SF_FLAGS(16, SF_NOCACHE) sendfile は、アプリケーションの指定された readahead (先読み) または内部で 計算されたどちらかより大きいほうを使用します。フラグ SF_USER_READAHEAD を 設定することは、あらゆる発見的手法をオフに切り替え、最大の指定できる readahead (先読み) の長さをフラグによって指定されたページの数に設定しま す。 実装に関する注 sendfile() の FreeBSD の実装は、ffs(7) ファイルシステムからのファイルを送 信するとき、ディスク I/O でブロックしません。syscall は、実際の I/O が完 了する前に、成功を返し、データは、後で参加されない (unattended) ソケット に置かれます。しかしながら、ソケットのデータの順序は、保存されますが、さ らにソケットに書き込みを行うことは安全です。 sendfile() の FreeBSD 実装は、"0 コピー" であり、ファイルのデータのコピー が避けられるように、最適化されたことを意味しています。 チューニング 物理的なページングバッファ sendfile() は、メモリにファイルページを読み込むために、vnode ページャを使 用します。ページャは、その I/O 操作を実行するために物理的なバッファのプー ルを使用します。システムが pbuf を使い果たすとき、sendfile は、状態 ``zonelimit'' をブロックし報告します。プールのサイズは、vm.vnode_pbufs loader.conf(5) 調整変数で調整することができ、実行時に同じ名前の sysctl(8) OID でチェックすることができます。 sendfile(2) バッファ いくつかのアーキテクチャで、このシステムコールは、ファイルデータをクライ アントに送信することを扱うために、特別の sendfile() バッファ (struct sf_buf) を内部で使用します。送信しているソケットがブロックされ、利用可能 な sendfile() バッファが十分でないなら、sendfile() は、``sfbufa'' の状態 をブロックして、報告します。送信しているソケットが非ブロッキングであり、 利用可能な sendfile() バッファが十分でないなら、呼び出しは、ブロックさ れ、呼び出しを終了する前に利用可能となる必要なバッファをウェート (待ち) します。 sf_buf の割り付けられた数は、データを sendfile() を通してクライアントに送 信するために使用される nmbclusters の数に比例しているべきです。ブロッキン グを避けるためにしかるべきに調整しましょう! sendfile() を広範囲に使用す る忙しい装置は、それらの kern.ipc.nmbclusters でインラインとなるように、 これらの値を増加したいかもしれません (詳細については、tuning(7) を参照)。 利用可能な sendfile() バッファの数は、kern.ipc.nsfbufs loader.conf(5) 変 数または NSFBUFS カーネル設定の調整変数のいずれかによって、ブート時に決定 されます。sendfile() バッファの数は、kern.maxusers で調整します。 kern.ipc.nsfbufsused と kern.ipc.nsfbufspeak の読み込み専用の sysctl(8) 変数は、それぞれ、現在とピークの sendfile() バッファの使用量を表示しま す。また、これらの値は、netstat -m を通して見られます。 sysctl(8) OID kern.ipc.nsfbufs が存在しないなら、利用者のアーキテクチャ は、それらのタスクが、一般的な仮想記憶構造によって効率的に実行することが できるので、sendfile() バッファを使用する必要はありません。 戻り値 関数 sendfile() は、処理が成功すると値 0 を返します。そうでない場合、値 -1 が返され、グローバル変数 errno にエラーを示す値が設定されます。 エラー [EAGAIN] ソケットが、非ブロッキング I/O のためにマークされ、す べてのデータが、満たされているソケットバッファのために 送信されるとは限りません。指定されるなら、成功して送信 されたバイト数は、*sbytes に返されます。 [EBADF] fd 引数が、有効なファイル記述子ではありません。 [EBADF] s 引数が、有効なソケット記述子ではありません。 [EBUSY] ビジーページに遭遇し、SF_NODISKIO が指定されました。部 分的なデータが送信されました。 [EFAULT] 無効のアドレスが、引数のために指定されました。 [EINTR] sendfile() が完了する前に、シグナルが割り込みました。 指定されるなら、成功して送信されたバイト数は、*sbytes に返されます。 [EINVAL] fd 引数が、通常のファイルではありません。 [EINVAL] s 引数が、SOCK_STREAM タイプのソケットではありません。 [EINVAL] offset 引数が、負です。 [EIO] fd から読み込む間に、エラーが起こりました。 [EINTEGRITY] 破損したデータが、fd から読み込む間に検出されました。 [ENOTCAPABLE] fd または s 引数に、十分な権利がありません。 [ENOBUFS] システムが、内部のバッファを割り付けることができません でした。 [ENOTCONN] s 引数が、接続されていないソケットを指しています。 [ENOTSOCK] s 引数が、ソケットではありません。 [EOPNOTSUPP] 記述子 fd のためのファイルシステムが、sendfile() をサ ポートしていません。 [EPIPE] ソケットの通信相手が接続を閉じました。 関連項目 netstat(1), open(2), send(2), socket(2), writev(2), loader.conf(5), tuning(7), sysctl(8) K. Elmeleegy, A. Chanda, A. L. Cox, and W. Zwaenepoel, "A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management", The Proceedings of the 2005 USENIX Annual Technical Conference, pp 223-236, 2005. 歴史 sendfile() システムコールは、FreeBSD 3.0 ではじめて登場しました。このマ ニュアルページは、FreeBSD 3.1 ではじめて登場しました。FreeBSD 10.0 で、共 用メモリ記述子を送信するためのサポートが導入されました。FreeBSD 11.0 で、 非ブロッキングの実装が、導入されました。 作者 sendfile() システムコールとこのマニュアルページの初期の実装は、David G. Lawrence <dg@dglawrence.com> によって書かれました。FreeBSD 11.0 の実装 は、 Gleb Smirnoff <glebius@FreeBSD.org> によって書かれました。 バグ sendfile() システムコールは、失敗しません、すなわち、sbytes のために無効 のアドレスが提供されるなら、-1 を返し、errno に EFAULT を設定します。 sendfile() システムコールは、SCTP ソケットをサポートせず、それは、-1 を返 し、errno を EINVAL に設定します。 FreeBSD 13.2 March 30, 2020 FreeBSD 13.2