.\" This manpage is Copyright (C) 1992 Drew Eckhardt; .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. .\" and Copyright (C) 2007 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith .\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith .\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt .\" .\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer .\" 2001-12-13 added remark by Zack Weinberg .\" 2007-06-18 mtk: .\" Added details about seekable files and file offset. .\" Noted that write() may write less than 'count' bytes, and .\" gave some examples of why this might occur. .\" Noted what happens if write() is interrupted by a signal. .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya .\" all rights reserved. .\" Translated Tue Mar 4 00:18:20 JST 1997 .\" by HANATAKA Shinya .\" Updated & Modified Wed Jun 13 20:57:55 JST 2001 .\" by Yuichi SATO .\" Updated Mon Jun 25 JST 2001 by Kentaro Shirakata .\" Updated Fri Dec 21 JST 2001 by Kentaro Shirakata .\" Updated 2002-09-24 by Akihiro MOTOKI .\" Updated 2005-10-14 by Akihiro MOTOKI .\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46 .\" Updated 2007-09-01, Akihiro MOTOKI, LDP v2.64 .\" Updated 2008-04-13, Akihiro MOTOKI, LDP v3.20 .\" Updated 2012-04-30, Akihiro MOTOKI .\" Updated 2013-05-04, Akihiro MOTOKI .\" .TH WRITE 2 2019\-10\-10 Linux "Linux Programmer's Manual" .SH 名前 write \- ファイルディスクリプター (file descriptor) に書き込む .SH 書式 \fB#include \fP .PP \fBssize_t write(int \fP\fIfd\fP\fB, const void *\fP\fIbuf\fP\fB, size_t \fP\fIcount\fP\fB);\fP .SH 説明 \fBwrite\fP() は、 \fIbuf\fP から始まるバッファーから、ファイルディスクリプター \fIfd\fP が参照するファイルへ、最大 \fIcount\fP バイトを書き込む。 .PP 書き込まれるバイト数は \fIcount\fP よりも小さくなることがある。 例えば、書き込み対象の物理メディアに十分な領域がない場合、 リソース上限 \fBRLIMIT_FSIZE\fP に達した場合 (\fBsetrlimit\fP(2) 参照)、 \fIcount\fP バイト未満の書き込みが行われた後で 呼び出しがシグナルハンドラーにより割り込まれた場合、 などである。 (\fBpipe\fP(7) も参照のこと。) .PP seek 可能なファイル (つまり \fBlseek\fP(2) が適用できるファイル、例えば通常のファイル) では、 書き込みはファイルオフセットから行われ、 ファイルオフセットは実際に書き込みが行われたバイト数分 加算される。ファイルが \fBO_APPEND\fP で \fBopen\fP(2) された場合、ファイルオフセットは書き込み前に ファイルの末尾に設定される。 ファイルオフセットの調整と書き込み操作はアトミックな処理として 実行される。 .PP POSIX は \fBwrite\fP() が行なわれた後に実行した \fBread\fP(2) が 新しいデータを返すことを要求している。 全てのファイルシステムが POSIX 準拠ではない点に注意すること。 .PP According to POSIX.1, if \fIcount\fP is greater than \fBSSIZE_MAX\fP, the result is implementation\-defined; see NOTES for the upper limit on Linux. .SH 返り値 成功すると、書き込まれたバイト数が返される。エラーの場合、 \-1 が返り、 \fIerrno\fP にエラーの原因を示す値が設定される。 .PP Note that a successful \fBwrite\fP() may transfer fewer than \fIcount\fP bytes. Such partial writes can occur for various reasons; for example, because there was insufficient space on the disk device to write all of the requested bytes, or because a blocked \fBwrite\fP() to a socket, pipe, or similar was interrupted by a signal handler after it had transferred some, but before it had transferred all of the requested bytes. In the event of a partial write, the caller can make another \fBwrite\fP() call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full). .PP \fIcount\fP が 0 で、 \fIfd\fP が通常のファイル (regular file) を参照している場合、 \fBwrite\fP() は後述のエラーのいずれかを検出した場合、失敗を返すことがある。 エラーが検出されなかった場合、もしくはエラー検出が実行されなかった場合、 0 が返され、他に何の影響も与えない。 \fIcount\fP が 0 で、 \fIfd\fP が通常のファイル以外のファイルを参照している場合、 その結果は規定されていない。 .SH エラー .TP \fBEAGAIN\fP ファイルディスクリプター \fIfd\fP がソケット以外のファイルを参照していて、 非停止 (nonblocking) モード (\fBO_NONBLOCK\fP) に設定されており、書き込みを行うと停止する状況にある。 \fBO_NONBLOCK\fP フラグの詳細は \fBopen\fP(2) を参照。 .TP \fBEAGAIN\fP または \fBEWOULDBLOCK\fP .\" Actually EAGAIN on Linux ファイルディスクリプター \fIfd\fP がソケットを参照していて、非停止 (nonblocking) モード (\fBO_NONBLOCK\fP) に設定されており、書き込みを行うと停止する状況にある。 POSIX.1\-2001 は、この場合にどちらのエラーを返すことも認めており、 これら 2 つの定数が同じ値を持つことも求めていない。 したがって、移植性が必要なアプリケーションでは、両方の可能性を 確認すべきである。 .TP \fBEBADF\fP \fIfd\fP が有効なファイルディスクリプターでないか書き込みのためにオープン (open) されていない。 .TP \fBEDESTADDRREQ\fP \fIfd\fP が、 \fBconnect\fP(2) を使って通信相手のアドレスが設定されていないデータグラムソケットを 参照している。 .TP \fBEDQUOT\fP \fIfd\fP が参照するファイルを含むファイルシステムのディスクブロックのユーザークォータの上限に達している。 .TP \fBEFAULT\fP \fIbuf\fP がアクセス可能なアドレス空間の外にある。 .TP \fBEFBIG\fP 実装定義の最大ファイルサイズまたはプロセスのファイルサイズ制限を 超えてファイルに書き込もうとした。 または許可されたオフセット値の限界を超えた先の位置に 書き込もうとした。 .TP \fBEINTR\fP 何のデータも書かない間にシグナルにより割り込まれた (interrupt)。 \fBsignal\fP(7) 参照。 .TP \fBEINVAL\fP \fIfd\fP が書き込みが不適切なオブジェクトを参照している。 もしくは、ファイルが \fBO_DIRECT\fP フラグを指定してオープンされているが、 \fIbuf\fP に指定されたアドレス、 \fIcount\fP に指定された値、 ファイルオフセットのいずれかのアラインメントが不適切である。 .TP \fBEIO\fP .\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 A low\-level I/O error occurred while modifying the inode. This error may relate to the write\-back of data written by an earlier \fBwrite\fP(), which may have been issued to a different file descriptor on the same file. Since Linux 4.13, errors from write\-back come with a promise that they \fImay\fP be reported by subsequent. \fBwrite\fP() requests, and \fIwill\fP be reported by a subsequent \fBfsync\fP(2) (whether or not they were also reported by \fBwrite\fP()). An alternate cause of \fBEIO\fP on networked filesystems is when an advisory lock had been taken out on the file descriptor and this lock has been lost. See the \fILost locks\fP section of \fBfcntl\fP(2) for further details. .TP \fBENOSPC\fP \fIfd\fP によって参照されるファイルを含むデバイス (device) に十分な空きがない。 .TP \fBEPERM\fP 操作が file seal により禁止されている。 \fBfcntl\fP(2) 参照。 .TP \fBEPIPE\fP \fIfd\fP がパイプ (pipe) かソケット (socket) に接続されており、 その反対側 (読み込み側) がクローズ (close) されている。 これが発生した場合には、書き込みを行なうプロセスは \fBSIGPIPE\fP シグナル (signal)も受ける。 (したがって、プログラムがこのシグナルを捕獲 (catch)、停止 (block)、無視 (ignore) した場合のみ、write の返り値を参照できる。) .PP \fIfd\fP に接続されたオブジェクトによっては、他のエラーが起こるかもしれない。 .SH 準拠 .\" SVr4 documents additional error .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. SVr4, 4.3BSD, POSIX.1\-2001. .PP SVr4 では write が割り込まれると、データが書き込まれる直前ではなく、 その時点で \fBEINTR\fP が返る。 .SH 注意 The types \fIsize_t\fP and \fIssize_t\fP are, respectively, unsigned and signed integer data types specified by POSIX.1. .PP A successful return from \fBwrite\fP() does not make any guarantee that data has been committed to disk. On some filesystems, including NFS, it does not even guarantee that space has successfully been reserved for the data. In this case, some errors might be delayed until a future \fBwrite\fP(), \fBfsync\fP(2), or even \fBclose\fP(2). The only way to be sure is to call \fBfsync\fP(2) after you are done writing all your data. .PP \fBwrite\fP() が 1 バイトも書き込まないうちにシグナルハンドラーにより割り込まれた場合、 \fBwrite\fP() はエラー \fBEINTR\fP で失敗する。 1バイトでも書き込んだ後で割り込まれた場合には、 \fBwrite\fP() は成功し、書き込んだバイト数を返す。 .PP .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 On Linux, \fBwrite\fP() (and similar system calls) will transfer at most 0x7ffff000 (2,147,479,552) bytes, returning the number of bytes actually transferred. (This is true on both 32\-bit and 64\-bit systems.) .PP An error return value while performing \fBwrite\fP() using direct I/O does not mean the entire write has failed. Partial data may be written and the data at the file offset on which the \fBwrite\fP() was attempted should be considered inconsistent. .SH バグ POSIX.1\-2008/SUSv4 セクション XSI 2.9.7 ("Thread Interactions with Regular File Operations") によると、 .PP .RS 4 以下のすべての関数では、 通常ファイルもしくはシンボリックリンクに対する操作では POSIX.1\-2008 で規定された効果が互いにアトミックに行われなければならない: ... .RE .PP .\" http://thread.gmane.org/gmane.linux.kernel/1649458 .\" From: Michael Kerrisk (man-pages gmail.com> .\" Subject: Update of file offset on write() etc. is non-atomic with I/O .\" Date: 2014-02-17 15:41:37 GMT .\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems .\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 .\" Author: Linus Torvalds .\" Date: Mon Mar 3 09:36:58 2014 -0800 .\" .\" vfs: atomic f_pos accesses as per POSIX この後に書かれている API の中に \fBwrite\fP() と \fBwritev\fP(2) である。 スレッド（やプロセス) 間でアトミックに適用することが求められる効果の一つとして、 ファイルオフセットの更新がある。 しかしながら、 バージョン 3.14 より前の Linux では、 この限りではない。 オープンファイル記述 (open file description) を共有する 2 つのプロセスが同時に \fBwrite\fP() (や \fBwritev\fP(2)) を実行した場合、 この I/O 操作ではファイルオフセットの更新に関してはアトミックではなく、 2 つのプロセスから出力されるデータブロックが (間違って) 重なる可能性がある。 この問題は Linux 3.14 で修正された。 .SH 関連項目 \fBclose\fP(2), \fBfcntl\fP(2), \fBfsync\fP(2), \fBioctl\fP(2), \fBlseek\fP(2), \fBopen\fP(2), \fBpwrite\fP(2), \fBread\fP(2), \fBselect\fP(2), \fBwritev\fP(2), \fBfwrite\fP(3) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。