release/man2/write.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   4 .\"                               1993 Michael Haardt, Ian Jackson.
   5 .\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   6 .\"
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\"
  27 .\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith <faith@cs.unc.edu>
  28 .\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith <faith@cs.unc.edu>
  29 .\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt
  30 .\"   <michael@cantor.informatik.rwth-aachen.de>
  31 .\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer <aeb@cwi.nl>
  32 .\" 2001-12-13 added remark by Zack Weinberg
  33 .\" 2007-06-18 mtk:
  34 .\"     Added details about seekable files and file offset.
  35 .\"     Noted that write() may write less than 'count' bytes, and
  36 .\"     gave some examples of why this might occur.
  37 .\"     Noted what happens if write() is interrupted by a signal.
  38 .\"
  39 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  40 .\"         all rights reserved.
  41 .\" Translated Tue Mar  4 00:18:20 JST 1997
  42 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  43 .\" Updated & Modified Wed Jun 13 20:57:55 JST 2001
  44 .\"         by Yuichi SATO <ysato@h4.dion.ne.jp>
  45 .\" Updated Mon Jun 25 JST 2001 by Kentaro Shirakata <argrath@ub32.org>
  46 .\" Updated Fri Dec 21 JST 2001 by Kentaro Shirakata <argrath@ub32.org>
  47 .\" Updated 2002-09-24 by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  48 .\" Updated 2005-10-14 by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  49 .\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46
  50 .\" Updated 2007-09-01, Akihiro MOTOKI, LDP v2.64
  51 .\" Updated 2008-04-13, Akihiro MOTOKI, LDP v3.20
  52 .\"
  53 .\"WORD:        descriptor              ディスクリプタ
  54 .\"WORD:        buffer                  バッファー
  55 .\"WORD:        file system             ファイル・システム
  56 .\"WORD:        object                  オブジェクト
  57 .\"WORD:        pipe                    パイプ
  58 .\"WORD:        socket                  ソケット
  59 .\"WORD:        signal                  シグナル
  60 .\"WORD:        catch                   捕獲(catch)
  61 .\"WORD:        block                   停止(block)
  62 .\"WORD:        interrupt               割り込み
  63 .\"WORD:        nonblocking I/O         非停止 I/O
  64 .\"WORD:        device                  デバイス
  65 .\"WORD:        low-level I/O           低レべル I/O
  66 .\"
  67 .TH WRITE 2 2010-08-29 "Linux" "Linux Programmer's Manual"
  68 .SH 名前
  69 write \- ファイル・ディスクリプタ (file descriptor) に書き込む
  70 .SH 書式
  71 .B #include <unistd.h>
  72 .sp
  73 .BI "ssize_t write(int " fd ", const void *" buf ", size_t " count );
  74 .SH 説明
  75 .BR write ()
  76 は、
  77 .I buf
  78 が指すバッファから、ファイル・ディスクリプタ
  79 .I fd
  80 が参照するファイルへ、最大
  81 .I count
  82 バイトを書き込む。
  83
  84 書き込まれるバイト数は
  85 .I count
  86 よりも小さくなることがある。
  87 例えば、書き込み対象の物理メディアに十分な領域がない場合、
  88 リソース上限
  89 .B RLIMIT_FSIZE
  90 に達した場合
  91 .RB ( setrlimit (2)
  92 参照)、
  93 .I count
  94 バイト未満の書き込みが行われた後で
  95 呼び出しがシグナルハンドラにより割り込まれた場合、
  96 などである。
  97 .RB ( pipe (7)
  98 も参照のこと。)
  99
 100 seek 可能なファイル (つまり
 101 .BR lseek (2)
 102 が適用できるファイル、例えば通常のファイル) では、
 103 書き込みは現在のファイル・オフセットから行われ、
 104 ファイル・オフセットは実際に書き込みが行われたバイト数分
 105 加算される。ファイルが
 106 .B O_APPEND
 107 で
 108 .BR open (2)
 109 された場合、ファイル・オフセットは書き込み前に
 110 ファイルの末尾に設定される。
 111 ファイル・オフセットの調整と書き込み操作はアトミックな処理として
 112 実行される。
 113
 114 POSIX は
 115 .BR write ()
 116 が行なわれた後に実行した
 117 .BR read (2)
 118 が
 119 新しいデータを返すことを要求している。
 120 全てのファイル・システムが POSIX 準拠ではない点に注意すること。
 121 .SH 返り値
 122 成功した場合、書き込まれたバイト数が返される
 123 (ゼロは何も書き込まれなかったことを示す)。
 124 エラーならば \-1 が返され、\fIerrno\fP が適切に設定される。
 125
 126 \fIcount\fP が 0 で、
 127 .I fd
 128 が通常のファイル (regular file) を参照している場合、
 129 .BR write ()
 130 は後述のエラーのいずれかを検出した場合、失敗を返すことがある。
 131 エラーが検出されなかった場合は、
 132 0 を返し、他に何の影響も与えない。
 133 \fIcount\fP が 0 で、
 134 .I fd
 135 が通常のファイル以外のファイルを参照している場合、
 136 その結果は規定されていない。
 137 .SH エラー
 138 .TP
 139 .B EAGAIN
 140 ファイル・ディスクリプタ
 141 .I fd
 142 がソケット以外のファイルを参照していて、
 143 非停止 (nonblocking) モード
 144 .RB ( O_NONBLOCK )
 145 に設定されており、書き込みを行うと停止する状況にある。
 146 .TP
 147 .BR EAGAIN " または " EWOULDBLOCK
 148 .\" Actually EAGAIN on Linux
 149 ファイル・ディスクリプタ
 150 .I fd
 151 がソケットを参照していて、非停止 (nonblocking) モード
 152 .RB  ( O_NONBLOCK )
 153 に設定されており、書き込みを行うと停止する状況にある。
 154 POSIX.1-2001 は、この場合にどちらのエラーを返すことも認めており、
 155 これら 2 つの定数が同じ値を持つことも求めていない。
 156 したがって、移植性が必要なアプリケーションでは、両方の可能性を
 157 確認すべきである。
 158 .TP
 159 .B EBADF
 160 .I fd
 161 が有効なファイル・ディスクリプタでないか書き込みのためにオープン
 162 (open) されていない。
 163 .TP
 164 .B EDESTADDRREQ
 165 .I fd
 166 が、
 167 .BR connect (2)
 168 を使って通信相手のアドレスが設定されていないデータグラムソケットを
 169 参照している。
 170 .TP
 171 .B EFAULT
 172 .I buf
 173 がアクセス可能なアドレス空間 (address space) の外にある。
 174 .TP
 175 .B EFBIG
 176 実装定義の最大ファイルサイズまたはプロセスのファイルサイズ制限を
 177 超えてファイルに書き込もうとした。
 178 または許可されたオフセット値の限界を超えた先の位置に
 179 書き込もうとした。
 180 .TP
 181 .B EINTR
 182 何のデータも書かない間にシグナルにより割り込まれた (interrupt)。
 183 .BR signal (7)
 184 参照。
 185 .TP
 186 .B EINVAL
 187 .I fd
 188 が書き込みが不適切なオブジェクトを参照している。
 189 もしくは、ファイルが
 190 .B O_DIRECT
 191 フラグを指定してオープンされているが、
 192 .I buf
 193 に指定されたアドレス、
 194 .I count
 195 に指定された値、
 196 現在のファイルオフセットのいずれかの
 197 アラインメントが不適切である。
 198 .TP
 199 .B EIO
 200 inode の修正中に低レべル (low-level) I/O エラーが発生した。
 201 .TP
 202 .B ENOSPC
 203 .I fd
 204 によって参照されるファイルを含むデバイス (device) に十分な空きがない。
 205 .TP
 206 .B EPIPE
 207 .I fd
 208 がパイプ (pipe) かソケット (socket) に接続されており、
 209 その反対側 (読み込み側) がクローズ (close) されている。
 210 これが発生した場合には、書き込みを行なうプロセスは
 211 .B SIGPIPE
 212 シグナル (signal)も受ける。
 213 (したがって、プログラムがこのシグナルを捕獲 (catch)、停止 (block)、無視 (ignore)
 214 した場合のみ、write の返り値を参照できる。)
 215 .PP
 216 .I fd
 217 に接続されたオブジェクトによっては、他のエラーが起こるかもしれない。
 218 .SH 準拠
 219 SVr4, 4.3BSD, POSIX.1-2001.
 220 .\" SVr4 には他に EDEADLK, ENOLCK, ENOLNK,
 221 .\" ENOSR, ENXIO, ERANGE エラーについての記述がある。
 222
 223 SVr4 では write が割り込まれると、データが書き込まれる直前ではなく、
 224 その時点で
 225 .B EINTR
 226 が返る。
 227 .SH 注意
 228 .BR write ()
 229 が成功して返ってきても、データがディスクに記録されたことを
 230 保証するものではない。
 231 実際、データのためのスペースが確保されたことすら保証されないという
 232 バグっぽい実装もある。
 233 これを確実にする唯一の方法は、
 234 全てのデータを write した後に
 235 .BR fsync (2)
 236 を呼び出すことである。
 237
 238 .BR write ()
 239 が 1 バイトも書き込まないうちにシグナルハンドラにより割り込まれた場合、
 240 .BR write ()
 241 はエラー
 242 .B EINTR
 243 で失敗する。
 244 1バイトでも書き込んだ後で割り込まれた場合には、
 245 .BR write ()
 246 は成功し、書き込んだバイト数を返す。
 247 .SH 関連項目
 248 .BR close (2),
 249 .BR fcntl (2),
 250 .BR fsync (2),
 251 .BR ioctl (2),
 252 .BR lseek (2),
 253 .BR open (2),
 254 .BR pwrite (2),
 255 .BR read (2),
 256 .BR select (2),
 257 .BR writev (2),
 258 .BR fwrite (3)