#include <dirent.h> struct dirent *readdir(DIR *dirp); int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);
glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):
readdir_r(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE
Linux では dirent 構造体は以下のように定義されている。
struct dirent {
ino_t d_ino; /* inode 番号 */
off_t d_off; /* 次の dirent へのオフセット */
unsigned short d_reclen; /* このレコードの長さ */
unsigned char d_type; /* ファイル種別。全ファイルシステム */
でサポートされているわけではない */
char d_name[256]; /* ファイル名 */
};
dirent 構造体のフィールドで POSIX.1 で要求されているのは、 d_name[] と (XSI 拡張での) d_ino だけである。 d_name[] はその大きさも規定されておらず、 このフィールドには最大で NAME_MAX 個の文字と、それに続く終端の NULL バイトが格納される。 他のフィールドは非標準であり、全てのシステムに存在するわけではない。 詳細については、下記の「注意」を参照のこと。
readdir() によって返されるデータは、それ以降の同じストリームに対する readdir() の呼び出しによって上書きされる可能性がある。
readdir_r() 関数は readdir() のリエントラント版である。 この関数はディレクトリストリーム dirp から次のディレクトリエントリを読み込み、 entry が指す呼び出し元が割り当てたバッファにそのエントリを格納して返す (このバッファの割り当てについては「注意」の節を参照のこと)。 返されるエントリへのポインタが *result に格納される。ディレクトリストリームの末尾に達した場合は、 NULL が *result に格納される。
成功すると、 readdir_r() 関数は 0 を返す。 エラーの場合、正のエラー番号を返す。 ディレクトリストリームの末尾に達した場合、 readdir_r() は返り値として 0 を返し、 *result に NULL を格納する。
d_type フィールドは、Linux 以外では、 主に BSD 系のシステムにだけ存在する。 このフィールドを使うと、 その後の動作がファイルの種別により決まる場合に、 lstat(2) を呼び出すコストを避けることができる。 機能検査マクロ _BSD_SOURCE が定義された場合、glibc は d_type で返される値として以下のマクロ定数を定義する。
ファイル種別を決定できなかった場合には、 d_type に DT_UNKNOWN が入る。
現在のところ、 d_type でファイルタイプを返す機能が完全にサポートされているのは、 いくつかのファイルシステムにおいてのみである (Btrfs, ext2, ext3, ext4 はサポートしている)。 どのアプリケーションも、 DT_UNKNOWN が返された際に適切に処理できなければならない。
POSIX.1 では d_name フィールドのサイズは規定されておらず、 dirent 構造体の d_name の後ろに他の非標準のフィールドがあるかもしれないので、 移植性が必要なアプリケーションで readdir_r() を使う場合は entry に渡すバッファを次のようにして割り当てるべきである。
len = offsetof(struct dirent, d_name) +
pathconf(dirpath, _PC_NAME_MAX) + 1
entryp = malloc(len);
(POSIX.1 では
struct dirent
の最後のフィールドが
d_name
であることを要求している。)