日本語 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.3-RELEASE-K, 13.0-RELEASE-K から 13.2-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() バッファ (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 を通して見られます。
kern.ipc.nsfbufs のために 0 の値が報告されるなら、利用者のアーキテクチャ
は、一般的な仮想メモリ構造によって、それらのタスクを効率的に実行すること
ができるので、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 s 引数に、十分な権利がありません。
[ENOBUFS] システムが、内部のバッファを割り付けることができません
でした。
[ENOTCONN] s 引数が、接続されていないソケットを指しています。
[ENOTSOCK] s 引数が、ソケットではありません。
[EOPNOTSUPP] 記述子 fd のためのファイルシステムが、sendfile() をサ
ポートしていません。
[EPIPE] ソケットの通信相手が接続を閉じました。
関連項目
netstat(1), open(2), send(2), socket(2), writev(2), tuning(7)
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 12.2 March 30, 2020 FreeBSD 12.2