.\" Copyright (c) 1989, 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.
.\"
.\"	@(#)getdirentries.2	8.2 (Berkeley) 5/3/95
.\" %FreeBSD: src/lib/libc/sys/getdirentries.2,v 1.23 2002/12/19 09:40:24 ru Exp %
.\"
.\" $FreeBSD$
.Dd May 3, 1995
.Dt GETDIRENTRIES 2
.Os
.Sh 名称
.Nm getdirentries ,
.Nm getdents
.Nd "ファイルシステムに独立なフォーマットのディレクトリエントリを取得する"
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In dirent.h
.Ft int
.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
.Ft int
.Fn getdents "int fd" "char *buf" "int nbytes"
.Sh 解説
.Fn getdirentries
システムコールと
.Fn getdents
システムコールは、ファイル記述子
.Fa fd
が参照するディレクトリから
.Fa buf
が指すバッファ内に、ファイルシステムに独立なフォーマットの
ディレクトリエントリを読み取ります。
最高で
.Fa nbytes
までのデータが転送されます。
.Fa nbytes
引数は、ファイルに対応するブロックサイズ以上である必要があります。
.Xr stat 2
を参照してください。
このサイズより小さいバッファでは、
これらのシステムコールをサポートしない可能性のあるファイルシステムがあります。
.Pp
バッファ内のデータは
.Vt dirent
構造体の連続で、それぞれ次のエントリが入っています:
.Bd -literal -offset indent
u_int32_t d_fileno;
u_int16_t d_reclen;
u_int8_t  d_type;
u_int8_t  d_namlen;
char	d_name[MAXNAMELEN + 1];	/* 下記を参照 */
.Ed
.Pp
.Fa d_fileno
エントリは、ファイルシステム内の異なるファイル毎に一意の数値です。
ハードリンクでリンクされたファイル
.Pf ( Xr link 2
を参照) は同じ
.Fa d_fileno
を持ちます。
.Fa d_reclen
エントリは、ディレクトリレコードの長さ (バイト単位) です。
.Fa d_type
エントリは、ディレクトリレコードが指すファイルのタイプです。
ファイルタイプの値は
.Fa <sys/dirent.h>
内に定義されます。
.Fa d_name
エントリにはヌル文字で終わるファイル名が入っています。
.Fa d_namlen
エントリは、ヌルバイトを除いたファイル名の長さを示します。
それゆえ、
.Fa d_name
の実際のサイズは 1 から
.Dv MAXNAMELEN
\&+ 1
の間のいずれかの値になります。
.Pp
エントリは余分のスペースで分離されているかもしれません。
.Fa d_reclen
エントリは、
.Fa dirent
構造体の開始点から次の構造体がある場合は
その構造体へのオフセットとして使用されます。
.Pp
実際に転送されたバイト数が返されます。
.Fa fd
に関連づけられた現在の位置を示すポインタは、
エントリの次のブロックに設定されます。
ポインタは
.Fn getdirentries
または
.Fn getdents
によって返されるバイト数分だけ進められるとは限りません。
ディレクトリの終わりに到達した場合は、値 0 が返されます。
.Pp
.Fn getdirentries
システムコールは、読み取られたブロック位置を
.Fa basep
が指す場所に書き込みます。
代わりに
.Xr lseek 2
によって現在の位置ポインタを設定、取得できます。
現在の位置ポインタは、
.Xr lseek 2
が返す値、
.Fa basep
が指す場所に返される値
.Fn ( getdirentries
のみ)、または 0 のいずれかにのみ設定するべきです。
.Sh 戻り値
処理が正常に完了すると、実際に転送されたバイト数が返されます。
そうでない場合は -1 が返され、エラーを示すためにグローバル変数
.Va errno
が設定されます。
.Sh エラー
.Fn getdirentries
システムコールは次の場合に失敗します:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa fd
引数が読取り用に開かれた有効なファイル記述子ではありません。
.It Bq Er EFAULT
.Fa buf
または
.Fa basep
のどちらかが、割り当てられたアドレス空間の範囲外を指しています。
.It Bq Er EINVAL
.Fa fd
によって参照されるファイルがディレクトリでないか、
.Fa nbytes
がディレクトリエントリまたはエントリのブロックを返すのには小さすぎます。
あるいは、現在の位置ポインタが無効です。
.It Bq Er EIO
ファイルシステムに読み書きしている間に
.Tn I/O
(入出力)エラーが発生しました。
.El
.Sh 関連項目
.Xr lseek 2 ,
.Xr open 2
.Sh 歴史
.Fn getdirentries
システムコールは
.Bx 4.4
ではじめて登場しました。
.Fn getdents
システムコールは
.Fx 3.0
ではじめて登場しました。