.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)write.2	8.5 (Berkeley) 4/2/94
.\" %FreeBSD: src/lib/libc/sys/write.2,v 1.26.2.1 2004/11/13 11:55:41 yar Exp %
.\"
.\" $FreeBSD$
.Dd October 16, 2004
.Dt WRITE 2
.Os
.Sh 名称
.Nm write ,
.Nm writev ,
.Nm pwrite
.Nd 出力の書込み
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In sys/uio.h
.In unistd.h
.Ft ssize_t
.Fn write "int d" "const void *buf" "size_t nbytes"
.Ft ssize_t
.Fn writev "int d" "const struct iovec *iov" "int iovcnt"
.Ft ssize_t
.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
.Sh 解説
.Fn write
システムコールは、
.Fa buf
が指すバッファから記述子
.Fa d
が参照するオブジェクトに
.Fa nbytes
のデータを書き込もうとします。
.Fn writev
システムコールは同様の動作をしますが、iov[0], iov[1], ..., iov[iovcnt-1] という
.Fa iov
配列のメンバが指定する
.Fa iovcnt
バッファから出力データを集めます。
.Fn pwrite
システムコールは同じ機能を実行しますが、ファイルポインタを修正せずに、
ファイルの特定場所に書き込みます。
.Pp
.Fn writev
では、
.Fa iovec
構造体が以下のように定義されています:
.Pp
.Bd -literal -offset indent -compact
struct iovec {
	void   *iov_base;    /* ベースアドレス */
	size_t  iov_len;     /* 長さ */
};
.Ed
.Pp
各
.Fa iovec
エントリは、書き込むデータがあるメモリのベースアドレスと
領域の長さを指定します。
.Fn writev
システムコールは、常に領域全体を書き込んでから次に進みます。
.Pp
シーク機能があるオブジェクトでは、
.Fn write
は
.Fa d
に関連するポインタが指定する位置で開始します。
.Xr lseek 2
を参照してください。
.Fn write
から戻ると、ポインタは書き込まれたバイト数だけ進みます。
.Pp
シーク機能がないオブジェクトでは、常に現在位置から書き込みます。
このようなオブジェクトに関連するポインタの値は未定義です。
.Pp
実ユーザがスーパユーザでない場合、
.Fn write
は、ユーザ ID 設定ビットをファイルでクリアします。
これにより、スーパユーザが所有する書込み可能なユーザ ID 設定ファイルを
.Dq 捕えた
ユーザは、システムセキュリティを突破できなくなります。
.Pp
ソケットのように、フロー制御の影響を受けるオブジェクトで
非ブロッキング I/O を使用すると、
.Fn write
と
.Fn writev
は、要求したより少ないバイト数を書き込むことがあります。
戻り値に注意し、可能な場合にはオペレーションの残りを再度試してください。
.Sh 戻り値
処理が正常に完了すると、書き込まれたバイト数が返されます。
そうでない場合は -1 が返され、エラーを示すためにグローバル変数
.Va errno
が設定されます。
.Sh エラー
.Fn write ,
.Fn writev
および
.Fn pwrite
システムコールは、以下の場合にエラーとなり、
ファイルポインタは変更されずに残ります:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa d
引数が、書込み用に開かれた有効な記述子ではありません。
.It Bq Er EPIPE
プロセスによる読取り用に開かれていないパイプに書き込もうとしました。
.It Bq Er EPIPE
通信相手のソケットに接続していないタイプ
.Dv SOCK_STREAM
のソケットに書き込もうとしました。
.It Bq Er EFBIG
プロセスのファイルサイズ制限か最大ファイルサイズを越えたファイルに
書き込もうとしました。
.It Bq Er EFAULT
.Fa iov
の一部、またはファイルに書き込むデータは、
プロセスに割り当てられたアドレス空間の範囲外を指しています。
.It Bq Er EINVAL
.Fa d
に関連するポインタが負になっています。
.It Bq Er ENOSPC
ファイルを含むファイルシステムに、充分なスペースが残っていません。
.It Bq Er EDQUOT
ファイルを含むファイルシステムのユーザのディスクブロック割当量が
使い尽くされています。
.It Bq Er EIO
ファイルシステムに読み書きしている間に入出力エラーが発生しました。
.It Bq Er EINTR
書込みが完了する前にシグナルが割り込みました。
.It Bq Er EAGAIN
ファイルは非ブロッキング入出力の印がついた状態で、しかも、
すぐにデータを書き込める状態ではありません。
.It Bq Er EROFS
スライスの先頭にあるディスクラベル領域に書込みを行おうとしました。
ディスクラベル領域への書込みを有効にするには
.Xr disklabel 8
.Fl W
を参照してください。
.El
.Pp
.Fn writev
は、以下のエラーを戻すことがあります:
.Bl -tag -width Er
.It Bq Er EDESTADDRREQ
.Xr connect 2
を使用して書込み先アドレスを設定した
.Ux
ドメインデータグラムソケットに書き込む場合に、書込み先が使用できません。
.It Bq Er EINVAL
.Fa iovcnt
引数が 0 以下になっているか、
.Dv IOV_MAX
より、大きくなっています。
.It Bq Er EINVAL
.Fa iov
配列
.Fa iov_len
値の 1 つが負になっています。
.It Bq Er EINVAL
.Fa iov
配列
.Fa iov_len
値の合計が、32 ビット整数をオーバフローしました。
.It Bq Er ENOBUFS
ソケットに書き出している時に mbuf のプールを使い尽くしました。
.El
.Pp
.Fn pwrite
システムコールは、以下のエラーを戻すことがあります:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa offset
の値が負です。
.It Bq Er ESPIPE
ファイル記述子が、パイプ、ソケット、FIFO に関連しています。
.El
.Sh 関連項目
.Xr fcntl 2 ,
.Xr lseek 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr select 2
.Sh 規格
.Fn write
システムコールは、
.St -p1003.1-90
に適合しています。
.Fn writev
システムコールと
.Fn pwrite
システムコールは、
.St -xpg4.2
に適合しています。
.Sh 歴史
.Fn pwrite
関数は、
.At V.4
で登場しました。
.Fn writev
システムコールは、
.Bx 4.2
で登場しました。
.Fn write
関数は、
.At v6
で登場しました。