| WRITE(2) | Linux Programmer's Manual | WRITE(2) |
名前¶
write - ファイルディスクリプタ (file descriptor) に書き込む
書式¶
#include <unistd.h>
ssize_t write(int fd, const void *buf, size_t count);
説明¶
write() は、 buf が指すバッファから、ファイルディスクリプタ fd が参照するファイルへ、最大 count バイトを書き込む。
書き込まれるバイト数は count よりも小さくなることがある。 例えば、書き込み対象の物理メディアに十分な領域がない場合、 リソース上限 RLIMIT_FSIZE に達した場合 (setrlimit(2) 参照)、 count バイト未満の書き込みが行われた後で 呼び出しがシグナルハンドラにより割り込まれた場合、 などである。 (pipe(7) も参照のこと。)
seek 可能なファイル (つまり lseek(2) が適用できるファイル、例えば通常のファイル) では、 書き込みは現在のファイルオフセットから行われ、 ファイルオフセットは実際に書き込みが行われたバイト数分 加算される。ファイルが O_APPEND で open(2) された場合、ファイルオフセットは書き込み前に ファイルの末尾に設定される。 ファイルオフセットの調整と書き込み操作はアトミックな処理として 実行される。
POSIX は write() が行なわれた後に実行した read(2) が 新しいデータを返すことを要求している。 全てのファイルシステムが POSIX 準拠ではない点に注意すること。
返り値¶
成功した場合、書き込まれたバイト数が返される (ゼロは何も書き込まれなかったことを示す)。 エラーならば -1 が返され、errno が適切に設定される。
count が 0 で、 fd が通常のファイル (regular file) を参照している場合、 write() は後述のエラーのいずれかを検出した場合、失敗を返すことがある。 エラーが検出されなかった場合は、 0 を返し、他に何の影響も与えない。 count が 0 で、 fd が通常のファイル以外のファイルを参照している場合、 その結果は規定されていない。
エラー¶
- EAGAIN
- ファイルディスクリプタ fd がソケット以外のファイルを参照していて、 非停止 (nonblocking) モード (O_NONBLOCK) に設定されており、書き込みを行うと停止する状況にある。
- EAGAIN または EWOULDBLOCK
- ファイルディスクリプタ fd がソケットを参照していて、非停止 (nonblocking) モード (O_NONBLOCK) に設定されており、書き込みを行うと停止する状況にある。 POSIX.1-2001 は、この場合にどちらのエラーを返すことも認めており、 これら 2 つの定数が同じ値を持つことも求めていない。 したがって、移植性が必要なアプリケーションでは、両方の可能性を 確認すべきである。
- EBADF
- fd が有効なファイルディスクリプタでないか書き込みのためにオープン (open) されていない。
- EDESTADDRREQ
- fd が、 connect(2) を使って通信相手のアドレスが設定されていないデータグラムソケットを 参照している。
- EDQUOT
- The user's quota of disk blocks on the file system containing the file referred to by fd has been exhausted.
- EFAULT
- buf がアクセス可能なアドレス空間の外にある。
- EFBIG
- 実装定義の最大ファイルサイズまたはプロセスのファイルサイズ制限を 超えてファイルに書き込もうとした。 または許可されたオフセット値の限界を超えた先の位置に 書き込もうとした。
- EINTR
- 何のデータも書かない間にシグナルにより割り込まれた (interrupt)。 signal(7) 参照。
- EINVAL
- fd が書き込みが不適切なオブジェクトを参照している。 もしくは、ファイルが O_DIRECT フラグを指定してオープンされているが、 buf に指定されたアドレス、 count に指定された値、 現在のファイルオフセットのいずれかの アラインメントが不適切である。
- EIO
- inode の修正中に低レべル (low-level) I/O エラーが発生した。
- ENOSPC
- fd によって参照されるファイルを含むデバイス (device) に十分な空きがない。
- EPIPE
- fd がパイプ (pipe) かソケット (socket) に接続されており、 その反対側 (読み込み側) がクローズ (close) されている。 これが発生した場合には、書き込みを行なうプロセスは SIGPIPE シグナル (signal)も受ける。 (したがって、プログラムがこのシグナルを捕獲 (catch)、停止 (block)、無視 (ignore) した場合のみ、write の返り値を参照できる。)
fd に接続されたオブジェクトによっては、他のエラーが起こるかもしれない。
準拠¶
SVr4, 4.3BSD, POSIX.1-2001.
SVr4 では write が割り込まれると、データが書き込まれる直前ではなく、 その時点で EINTR が返る。
注意¶
write() が成功して返ってきても、データがディスクに記録されたことを 保証するものではない。 実際、データのためのスペースが確保されたことすら保証されないという バグっぽい実装もある。 これを確実にする唯一の方法は、 全てのデータを write した後に fsync(2) を呼び出すことである。
write() が 1 バイトも書き込まないうちにシグナルハンドラにより割り込まれた場合、 write() はエラー EINTR で失敗する。 1バイトでも書き込んだ後で割り込まれた場合には、 write() は成功し、書き込んだバイト数を返す。
関連項目¶
close(2), fcntl(2), fsync(2), ioctl(2), lseek(2), open(2), pwrite(2), read(2), select(2), writev(2), fwrite(3)
この文書について¶
この man ページは Linux man-pages プロジェクトのリリース 3.51 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
| 2013-01-27 | Linux |