Manpages

名 前

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 を 格 納 す る 。

エ ラ ー

属 性

マ ル チ ス レ ッ デ ィ ン グ (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 で 返 さ れ る 値 と し て 以 下 の マ ク ロ 定 数 を 定 義 す る 。

(FIFO) で あ る 。

UNIX ド メ イ ン ソ ケ ッ ト で あ る 。

現 在 の と こ ろ 、 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/ に 書 か れ て い る 。