名称

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

ライブラリ

Standard C Library (libc, -lc)

書式

#include < sys/types.h>
#include < 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 構造体の連続で、それぞれ次のエントリが入っています:

uint32_t d_fileno; 
uint16_t d_reclen; 
uint8_t  d_type; 
uint8_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 ではじめて登場しました。