Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all 
名前
readdir, readdir_r - ディレクトリを読み込む
書式
#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
説明
readdir() 関数は、dirp が指すディレクトリストリームの中で、 次のディレクトリエントリーを
表す dirent 構造体へのポインターを返す。 ディレクトリストリームの末尾に達した場合や、 エ
ラーが発生した場合は、 NULL を返す。
Linux では dirent 構造体は以下のように定義されている。
struct dirent {
ino_t d_ino; /* inode 番号 */
off_t d_off; /* オフセットではない; 注意を参照 */
unsigned short d_reclen; /* このレコードの長さ */
unsigned char d_type; /* ファイル種別。全ファイルシステム */
でサポートされているわけではない */
char d_name[256]; /* ファイル名 */
};
dirent 構造体のフィールドで POSIX.1 で要求されているのは、 d_name[] と (XSI 拡張での)
d_ino だけである。 d_name[] はその大きさも規定されておらず、 このフィールドには最大で
NAME_MAX 個の文字と、それに続く終端の ヌルバイト ('\0')が格納される。 他のフィールドは非標
準であり、全てのシステムに存在するわけではない。 詳細については、下記の「注意」を参照のこ
と。
readdir() によって返されるデータは、それ以降の同じストリームに対する readdir() の呼び出し
によって上書きされる可能性がある。
readdir_r() 関数は readdir() のリエントラント版である。 この関数はディレクトリストリーム
dirp から次のディレクトリエントリーを読み込み、 entry が指す呼び出し元が割り当てたバッ
ファーにそのエントリーを格納して返す (このバッファーの割り当てについては「注意」の節を参照
のこと)。 返されるエントリーへのポインターが *result に格納される。ディレクトリストリーム
の末尾に達した場合は、 NULL が *result に格納される。
返り値
成功すると、 readdir() は dirent 構造体へのポインターを返す。 (この構造体は静的に割り当て
られているかもしれない。 このポインターを free(3) しようとしないこと。) ディレクトリスト
リームの末尾に達した場合には、NULL が返され、 errno は変化しない。 エラーが発生した場
合、NULL が返され、 errno が適切に設定される。
成功すると、 readdir_r() 関数は 0 を返す。 エラーの場合、(「エラー」の節のリストに載って
いる) 正のエラー番号を返す。 ディレクトリストリームの末尾に達した場合、 readdir_r() は返
り値として 0 を返し、 *result に NULL を格納する。
エラー
EBADF ディレクトリストリームディスクリプター dirp が無効である。
属性
マルチスレッディング (pthreads(7) 参照) readdir() 関数はスレッドセーフではない。 readdir_r() 関数はスレッドセーフである。
準拠
SVr4, 4.3BSD, POSIX.1-2001.
注意
フィールド d_name と d_ino だけが POSIX.1-2001 で規定されている。 残りのフィールドは多くの
システムに存在するが、全てのシステムに 存在するわけではない。 glibc では、プログラムが
POSIX.1 で定義されていないフィールドが 利用できるかをチェックすることができる。 チェックす
るには、マクロ _DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF,
_DIRENT_HAVE_D_TYPE が定義されているかをテストすればよい。
d_off で返される値は telldir(3) が返す値と同じで、ディレクトリストリーム内の現在の位置を示
す。 フィールドの型や名前はこうなっていますが、最近のファイルシステムでは d_off フィールド
が何らかのディレクトリオフセットであることはめったいにない。アプリケーションプログラムで
は、必ずこの値を内容を意識せず単なる値として扱うべきであり、その内容について前提を持つべき
ではない。
d_type フィールドは、Linux 以外では、 主に BSD 系のシステムにだけ存在する。 このフィールド
を使うと、 その後の動作がファイルの種別により決まる場合に、 lstat(2) を呼び出すコストを避
けることができる。 機能検査マクロ _BSD_SOURCE が定義された場合、glibc は d_type で返される
値として以下のマクロ定数を定義する。
DT_BLK ブロックデバイスである。
DT_CHR キャラクターデバイスである。
DT_DIR ディレクトリである。
DT_FIFO 名前付きパイプ (FIFO) である。
DT_LNK シンボリックリンクである。
DT_REG 通常のファイルである。
DT_SOCK UNIX ドメインソケットである。
DT_UNKNOWN ファイルタイプが不明である。
ファイル種別を決定できなかった場合には、 d_type に DT_UNKNOWN が入る。
現在のところ、 d_type でファイルタイプを返す機能が完全にサポートされているのは、 いくつか
のファイルシステムにおいてのみである (Btrfs, ext2, ext3, ext4 はサポートしている)。 どのア
プリケーションも、 DT_UNKNOWN が返された際に適切に処理できなければならない。
POSIX.1 では d_name フィールドのサイズは規定されておらず、 dirent 構造体の d_name の後ろに
他の非標準のフィールドがあるかもしれないので、 移植性が必要なアプリケーションで
readdir_r() を使う場合は entry に渡すバッファーを次のようにして割り当てるべきである。
name_max = pathconf(dirpath, _PC_NAME_MAX);
if (name_max == -1) /* 上限が定義されていない、またはエラー */
name_max = 255; /* 適当な値を入れる */
len = offsetof(struct dirent, d_name) + name_max + 1;
entryp = malloc(len);
(POSIX.1 では struct dirent の最後のフィールドが d_name であることを要求している。)
関連項目
getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3),
rewinddir(3), scandir(3), seekdir(3), telldir(3)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクト
の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
2013-06-21 READDIR(3)