.\" 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.
.\"
.\"     @(#)read.2	8.4 (Berkeley) 2/26/94
.\" %FreeBSD: src/lib/libc/sys/read.2,v 1.9.2.5 2001/08/17 15:42:45 ru Exp %
.\"
.\" $FreeBSD: doc/ja_JP.eucJP/man/man2/read.2,v 1.7 2001/07/29 05:15:14 horikawa Exp $
.Dd February 26, 1994
.Dt READ 2
.Os
.Sh 名称
.Nm read ,
.Nm readv ,
.Nm pread
.Nd 入力を読取る
.Sh ライブラリ
.Lb libc
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <sys/uio.h>
.Fd #include <unistd.h>
.Ft ssize_t
.Fn read "int d" "void *buf" "size_t nbytes"
.Ft ssize_t
.Fn readv "int d" "const struct iovec *iov" "int iovcnt"
.Ft ssize_t
.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
.Sh 解説
.Fn read
は、記述子
.Fa d
で参照されたオブジェクトから
.Fa buf
が指すバッファへ
.Fa nbytes
のデータを読取ろうとします。
.Fn readv
は同様の処理を実行しますが、配列
.Fa iov
: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]
のメンバで指定される
.Fa iovcnt
個のバッファに入力データを分散
させます。
.Fn pread
は同様の機能を実行しますが、ファイル内の指定の位置から読取った後、
ファイルポインタを変更しません。
.Pp
.Fn readv
に対する
.Fa iovec
構造体は次のように定義されます。
.Pp
.Bd -literal -offset indent -compact
struct iovec {
	char   *iov_base;  /* ベースアドレス */
	size_t iov_len;    /* 長さ */
};
.Ed
.Pp
.Fa iovec
の各エントリは、データを配置するべきメモリ領域のベースアドレスと
長さを指定しています。
.Fn readv
は、次のエントリに進む前に必ず領域を完全に満たします。
.Pp
シーク可能なオブジェクト上では
.Fn read
は
.Fa d
に結び付けられたポインタが指定する位置から開始
します
.Pf ( Xr lseek 2
を参照)。
.Fn read
からの戻り時に、ポインタは実際に読取られたバイト数
だけ増加させられます。
.Pp
シークできないオブジェクトは必ず現在の位置から読取られます。
そのようなオブジェクトに結び付けられたポインタの値は未定義です。
.Pp
処理が成功すると、
.Fn read ,
.Fn readv
および
.Fn pread
は、実際に読取られバッファ内に配置されたバイト
数を返します。記述子が通常ファイルを参照しており、
ファイルの終端までに十分な量のバイトがあれば、
システムは要求されたバイト数を読取ることを保証しますが、
他のケースではそうではありません。
.Sh 実装に関する注
非スレッドライブラリでは、
.Fn read
は
.Va read
システムコールとして実装されています。
.Pp
スレッドライブラリでは、
.Va read
システムコールは
.Fn _thread_sys_read
にアセンブルされ、
.Fn read
は読取り用に
.Fa d
をロックしてから
.Fn _thread_sys_read
を呼び出す関数として実装されています。
.Fn _thread_sys_read
の呼び出しがブロックする場合は、コンテキストスイッチが実行されます。
戻る前に
.Fn read
は
.Fa d
をアンロックします。
.Pp
非スレッドライブラリでは、
.Fn readv
は
.Va readv
システムコールとして実装されています。
.Pp
スレッドライブラリでは、
.Va readv
システムコールは
.Fn _thread_sys_readv
システムコールにアセンブルされ、
.Fn readv
は、読取り用に
.Fa d
をロックしてから
.Fn _thread_sys_readv
を呼び出す関数として実装されています。
.Fn _thread_sys_readv
の呼び出しがブロックする場合、コンテキストスイッチが実行されます。
戻る前に
.Fn readv
は
.Fa d
をアンロックします。
.Sh 戻り値
正常に完了すると、実際に読取られたバイト数が返されます。
ファイル終了 (EOF) が読取られると
0 が返されます。そうでない場合は -1 が返され、
エラーを示すためにグローバル変数
.Va errno
が設定されます。
.Sh エラー
.Fn read ,
.Fn readv
および
.Fn pread
は次の場合を除いて正常に完了します。
.Bl -tag -width Er
.It Bq Er EBADF
.Fa d
は読取り用にオープンされた有効なファイルまたはソケットの記述子ではありません。
.It Bq Er EFAULT
.Fa buf
は、プロセスに割り当てられたアドレス空間の範囲外を指しています。
.It Bq Er EIO
ファイルシステムから読取っている間に入出力エラーが発生しました。
.It Bq Er EINTR
データが到着する前に、シグナルの配送により低速デバイスからの読取りが
割り込まれました。
.It Bq Er EINVAL
.Fa d
に結び付けられたポインタが負でした。
.It Bq Er EAGAIN
ファイルは非ブロッキング入出力とマークされており、
読取りの準備ができたデータがありません。
.El
.Pp
さらに、
.Fn readv
は次のエラーのうちの 1 つを返すことがあります。
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa iovcnt
が 0 以下であるか、または 16 より大きくなっています。
.It Bq Er EINVAL
.Fa iov
配列の中の
.Fa iov_len
値の 1 つが負でした。
.It Bq Er EINVAL
.Fa iov
配列の中の
.Fa iov_len
値の合計が 32 ビット整数をオーバーフローしました。
.It Bq Er EFAULT
.Fa iov
の一部が、プロセスに割り当てられたアドレス空間の範囲外を指しています。
.El
.Pp
.Fn pread
呼び出しも次のエラーを返すことがあります。
.Bl -tag -width Er
.It Bq Er EINVAL
指定のファイルオフセットが有効ではありません。
.It Bq Er ESPIPE
ファイル記述子がパイプ、ソケット、または FIFO に結び付けられています。
.El
.Sh 関連項目
.Xr dup 2 ,
.Xr fcntl 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr socketpair 2
.Sh 規格
.Fn read
関数は
.St -p1003.1-90
に準拠しています。
.Fn readv
関数と
.Fn pread
関数は
.St -xpg4.2
に準拠しています。
.Sh 歴史
.Fn pread
関数は
.At V.4
で登場しました。
.Fn readv
関数は
.Bx 4.2
で登場しました。
.Fn read
関数は
.At v6
で登場しました。