.\" 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.25.2.1 2004/11/13 11:55:41 yar Exp %
.\"
.\" $FreeBSD$
.Dd October 16, 2004
.Dt READ 2
.Os
.Sh 名称
.Nm read ,
.Nm readv ,
.Nm pread
.Nd 入力を読み取る
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In sys/uio.h
.In 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 {
	void   *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 戻り値
正常に完了すると、実際に読み取られたバイト数が返されます。
ファイル終了 (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
ファイルは非ブロッキング入出力とマークされており、
読取りの準備ができたデータがありません。
.It Bq Er EISDIR
ファイル記述子が、ディレクトリ上での普通の読み込み操作を許可していない
ファイルシステム (例えば NFS) に属しているディレクトリに
関連付けられています。
.It Bq Er EOPNOTSUPP
ファイル記述子が、普通の読み込み操作を許可していないファイルシステムおよび
ファイルタイプに関連付けられています。
.It Bq Er EOVERFLOW
ファイル記述子が普通のファイルに関連付けられていて、
.Fa nbytes
が 0 よりも大きく、
.Fa offset
がファイルの末尾の前にあり、かつ
.Fa offset
がこのファイルシステムに収まるオフセットの最大値以上です。
.El
.Pp
さらに、
.Fn readv
は次のエラーのうちの 1 つを返すことがあります:
.Bl -tag -width Er
.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 EFAULT
.Fa iov
の一部が、プロセスに割り当てられたアドレス空間の範囲外を指しています。
.El
.Pp
.Fn pread
システムコールは次のエラーを返すこともあります:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa offset
の値が負です。
.It Bq Er ESPIPE
ファイル記述子がパイプ、ソケット、または FIFO に結び付けられています。
.El
.Sh 関連項目
.Xr dup 2 ,
.Xr fcntl 2 ,
.Xr getdirentries 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr socketpair 2 ,
.Xr fread 3 ,
.Xr readdir 3
.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
で登場しました。