getdirentries(2)

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

標準 C ライブラリ (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 構造体の連続で、それぞれ次のエントリが入って います:

      u_int32_t d_fileno;
      u_int16_t d_reclen;
      u_int8_t  d_type;
      u_int8_t  d_namlen;

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() システムコールは次の場合に失敗します:

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

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

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

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

関連項目

lseek(2), open(2)

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

FreeBSD 10.0 May 3, 1995 FreeBSD 10.0