.\" 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.12.2.3 2001/03/05 11:44:37 obrien Exp %
.\"
.Dd April 2, 1994
.Dt WRITE 2
.Os BSD 4
.Sh 名称
.Nm write ,
.Nm writev ,
.Nm pwrite
.Nd 出力の書込み
.Sh ライブラリ
.Lb libc
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <sys/uio.h>
.Fd #include <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 {
	char   *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
は、set-user-ID ビットをファイルでクリアします。
これにより、スーパユーザが所有する書込み可能な set-user-ID ファイルを
「捕えた」ユーザは、システムセキュリティを突破できなくなります。
.Pp
ソケットのように、フローコントロールの影響を受けるオブジェクトで
非ブロッキング I/O を使用すると、
.Fn write
と
.Fn writev
は、要求したより少ないバイト数を書込むことがあります。
戻り値に注意し、可能な場合にはオペレーションの残りを再度試してください。
.Sh 実装上の注意事項
非スレッドライブラリでは、
.Fn write
は
.Va write
システムコールのように実装されます。
.Pp
スレッドライブラリでは、
.Fn write
システムコールは
.Fn _thread_sys_write
に組み込まれ、
.Fn write
は、読み書き用に
.Fa d
をロックしてから
.Fn _thread_sys_write
を呼び出す関数のように実装されます。
.Va _thread_sys_write
の呼び出しがブロックする場合は、コンテキストスイッチが実行されます。
.Fn write
は戻る前に
.Fa d
のロックを解除します。
.Pp
非スレッドライブラリでは、
.Fn writev
は
.Va writev
システムコールのように実装されます。
.Pp
スレッドライブラリでは、
.Fn writev
システムコールは
.Fn _thread_sys_writev
に組み込まれ、
.Fn writev
は、読み書き用に
.Fa d
をロックしてから
.Fn _thread_sys_writev
を呼び出す関数のように実装されます。
.Fn _thread_sys_writev
の呼び出しがブロックする場合は、コンテキストスイッチが実行されます。
.Fn writev
は戻る前に
.Fa d
のロックを解除します。
.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
ファイルは非ブロッキング入出力の印がついた状態で、しかも、
すぐにデータを書込める状態ではありません。
.El
.Pp
.Fn writev
は、以下のエラーを戻すことがあります。
.Bl -tag -width Er
.It Bq Er EDESTADDRREQ
.Xr connect 2
を使用して書込み先アドレスを設定した
.Ux
ドメインデータグラムソケットに書込む場合に、書込み先が使用できません。
.It Bq Er EINVAL
.Fa iovcnt
が 0 以下になっているか、
.Dv UIO_MAXIOV
より、大きくなっています。
.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
指定したファイルオフセットが正しくありません。
.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
で登場しました。