GETDIRENTRIES(2)

名称
getdirentries, getdents - ファイルシステムに独立なフォーマットのディレクトリエントリを取得する

ライブラリ
libc

書式
<sys/types.h> <dirent.h> int getdirentries(int fd, char *buf, int nbytes, long *basep) int getdents(int fd, char *buf, int nbytes)

解説
getdirentries() システムコールと getdents() システムコールは、ファイル記述子 fd が参照するディレクトリから buf が指すバッファ内に、ファイルシステムに独立なフォーマットの ディレクトリエントリを読み取ります。 最高で nbytes までのデータが転送されます。 nbytes 引数は、ファイルに対応するブロックサイズ以上である必要があります。 stat(2) を参照してください。 このサイズより小さいバッファでは、 これらのシステムコールをサポートしない可能性のあるファイルシステムがあります。

バッファ内のデータは dirent 構造体の連続で、それぞれ次のエントリが入っています:

    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];	/* 下記を参照 */

d_fileno エントリは、ファイルシステム内の異なるファイル毎に一意の数値です。 ハードリンクでリンクされたファイル (link(2) を参照) は同じ d_fileno を持ちます。 d_reclen エントリは、ディレクトリレコードの長さ (バイト単位) です。 d_type エントリは、ディレクトリレコードが指すファイルのタイプです。 ファイルタイプの値は <sys/dirent.h> 内に定義されます。 d_name エントリにはヌル文字で終わるファイル名が入っています。 d_namlen エントリは、ヌルバイトを除いたファイル名の長さを示します。 それゆえ、 d_name の実際のサイズは 1 から MAXNAMELEN + 1 の間のいずれかの値になります。

エントリは余分のスペースで分離されているかもしれません。 d_reclen エントリは、 dirent 構造体の開始点から次の構造体がある場合は その構造体へのオフセットとして使用されます。

実際に転送されたバイト数が返されます。 fd に関連づけられた現在の位置を示すポインタは、 エントリの次のブロックに設定されます。 ポインタは getdirentries() または getdents() によって返されるバイト数分だけ進められるとは限りません。 ディレクトリの終わりに到達した場合は、値 0 が返されます。

getdirentries() システムコールは、読み取られたブロック位置を basep が指す場所に書き込みます。 代わりに lseek(2) によって現在の位置ポインタを設定、取得できます。 現在の位置ポインタは、 lseek(2) が返す値、 basep が指す場所に返される値 ((getdirentries) のみ)、または 0 のいずれかにのみ設定するべきです。

戻り値
処理が正常に完了すると、実際に転送されたバイト数が返されます。 そうでない場合は -1 が返され、エラーを示すためにグローバル変数 errno が設定されます。

エラー
getdirentries() システムコールは次の場合に失敗します:

[EBADF]
    fd 引数が読取り用に開かれた有効なファイル記述子ではありません。

[EFAULT]
    buf または basep のどちらかが、割り当てられたアドレス空間の範囲外を指しています。

[EINVAL]
    fd によって参照されるファイルがディレクトリでないか、 nbytes がディレクトリエントリまたはエントリのブロックを返すのには小さすぎます。 あるいは、現在の位置ポインタが無効です。

[EIO]
    ファイルシステムに読み書きしている間に I/O (入出力)エラーが発生しました。

関連項目
lseek(2), open(2)

歴史
getdirentries() システムコールは 4.4BSD ではじめて登場しました。 getdents() システムコールは FreeBSD 3.0 ではじめて登場しました。