Man page - readdir(3)

Packages contains this manual

Available languages:

en fr ja ru ro de

Manual

READDIR

名 前
書 式
説 明
返 り 値
エ ラ ー
属 性
準 拠
注 意
d_name フ ィ ー ル ド
関 連 項 目
こ の 文 書 に つ い て

名 前

readdir - デ ィ レ ク ト リ を 読 み 込 む

書 式

#include <dirent.h>

struct dirent *readdir(DIR * dirp );

説 明

readdir () 関 数 は 、 dirp が 指 す デ ィ レ ク ト リ ス ト リ ー ム の 中 で 、 次 の デ ィ レ ク ト リ エ ン ト リ ー を 表 す dirent 構 造 体 へ の ポ イ ン タ ー を 返 す 。 デ ィ レ ク ト リ ス ト リ ー ム の 末 尾 に 達 し た 場 合 や 、 エ ラ ー が 発 生 し た 場 合 は 、 NULL を 返 す 。

glibc の 実 装 で は 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 と d_ino だ け で あ る 。 他 の フ ィ ー ル ド は 非 標 準 で あ り 、 す べ て の シ ス テ ム で 存 在 す る わ け で は な い 。 詳 細 に つ い て は 、 下 記 の 「 注 意 」 を 参 照 の こ と 。

dirent 構 造 体 の フ ィ ー ル ド は 以 下 の 通 り で あ る :

d_ino

フ ァ イ ル の inode 番 号 で あ る 。

d_off

d_off で 返 さ れ る 値 は 、 デ ィ レ ク ト リ ス ト リ ー ム の 現 在 の 位 置 で telldir (3) を 呼 び 出 し た 場 合 の 返 り 値 と 同 じ で あ る 。 フ ィ ー ル ド の 型 や 名 前 は こ う な っ て い る が 、 最 近 の フ ァ イ ル シ ス テ ム で は d_off フ ィ ー ル ド が 何 ら か の デ ィ レ ク ト リ オ フ セ ッ ト で あ る こ と は め っ た に な い 。 ア プ リ ケ ー シ ョ ン プ ロ グ ラ ム で は 、 必 ず こ の 値 を 内 容 を 意 識 せ ず 単 な る 値 と し て 扱 う べ き で あ り 、 そ の 内 容 に つ い て 前 提 を 持 つ べ き で は な い 。 telldir (3) も 参 照 。

d_reclen

返 さ れ た レ コ ー ド の (バ イ ト 単 位 の ) サ イ ズ で あ る 。 こ の 値 は 上 記 の 構 造 体 の 定 義 の サ イ ズ と は 一 致 し な い か も し れ な い 。 「 注 意 」 を 参 照 。

d_type

フ ァ イ ル 種 別 を 示 す 値 が 格 納 さ れ る 。 こ れ に よ り 、 こ れ 以 降 の 処 理 が フ ァ イ ル 種 別 に 依 存 し て い る 場 合 に lstat (2) を 呼 び 出 す コ ス ト を 避 け る こ と が で き る 。

適 切 な 機 能 検 査 マ ク ロ (glibc 2.19 以 降 で は _DEFAULT_SOURCE 、 glibc 2.19 以 前 で は _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 で フ ァ イ ル タ イ プ を 返 す 機 能 が 完 全 に サ ポ ー ト さ れ て い る の は 、 い く つ か の フ ァ イ ル シ ス テ ム に お い て の み で あ る (Btrfs, ext2, ext3, ext4 は サ ポ ー ト し て い る )。 ど の ア プ リ ケ ー シ ョ ン も DT_UNKNOWN が 返 さ れ た 際 に 適 切 に 処 理 で き な け れ ば な ら な い 。

d_name

こ の フ ィ ー ル ド は ヌ ル 終 端 さ れ た フ ァ イ ル 名 で あ る 。 「 注 意 」 を 参 照 。

readdir () に よ っ て 返 さ れ る デ ー タ は 、 そ れ 以 降 の 同 じ ス ト リ ー ム に 対 す る readdir () の 呼 び 出 し に よ っ て 上 書 き さ れ る 可 能 性 が あ る 。

返 り 値

成 功 す る と 、 readdir () は dirent 構 造 体 へ の ポ イ ン タ ー を 返 す 。 (こ の 構 造 体 は 静 的 に 割 り 当 て ら れ て い る か も し れ な い 。 こ の ポ イ ン タ ー を free (3) し よ う と し な い こ と 。 )

デ ィ レ ク ト リ ス ト リ ー ム の 末 尾 に 達 し た 場 合 に は 、 NULL が 返 さ れ 、 errno は 変 化 し な い 。 エ ラ ー が 発 生 し た 場 合 、 NULL が 返 さ れ 、 errno が 適 切 に 設 定 さ れ る 。 エ ラ ー か ら ス ト リ ー ム の 末 尾 を 区 別 す る に は 、 readdir () を 呼 び 出 す 前 に errno を 0 に 設 定 し て お き 、 NULL が 返 さ れ た 場 合 に errno の 値 を 確 認 す れ ば よ い 。

エ ラ ー

EBADF

デ ィ レ ク ト リ ス ト リ ー ム デ ィ ス ク リ プ タ ー dirp が 無 効 で あ る 。

属 性

こ の 節 で 使 用 さ れ て い る 用 語 の 説 明 に つ い て は 、 attributes (7) を 参 照 。

Image grohtml-43687-1.png

現 在 の POSIX.1 標 準 (POSIX.1-2008) で は 、 readdir () が ス レ ッ ド セ ー フ で あ る こ と は 求 め ら れ て い な い 。 し か し な が ら 、 最 近 の 実 装 (glibc に よ る 実 装 も 含 む ) で は 、 異 な る デ ィ レ ク ト リ ス ト リ ー ム に 対 す る readdir () の 同 時 並 行 の 呼 び 出 し は ス レ ッ ド セ ー フ で あ る 。 複 数 の ス レ ッ ド が 同 じ デ ィ レ ク ト リ ス ト リ ー ム か ら 読 み 込 み を 行 う 必 要 が あ る 場 合 も 、 非 推 奨 の readdir_r (3) 関 数 を 使 用 す る よ り も 、 外 部 同 期 を 用 い た readdir () を 使 う 方 が 推 奨 さ れ る 。 POSIX.1 の 将 来 の バ ー ジ ョ ン で は 、 readdir () は 異 な る デ ィ レ ク ト リ ス ト リ ー ム に 対 し て 同 時 に 使 用 さ れ た 際 に ス レ ッ ド セ ー フ で あ る こ と が 必 須 と な る 予 定 で あ る 。

準 拠

POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.

注 意

デ ィ レ ク ト リ ス ト リ ー ム は opendir (3) を 使 っ て オ ー プ ン す る 。

連 続 す る readdir () の 呼 び 出 し で 読 み 込 ま れ る フ ァ イ ル 名 の 順 序 は 、 フ ァ イ ル シ ス テ ム の 実 装 に 依 存 す る 。 名 前 が 何 ら か の 方 法 で ソ ー ト さ れ て い る こ と は あ り え な い 。

フ ィ ー ル ド d_name と (XSI 拡 張 の ) d_ino だ け が POSIX.1 で 規 定 さ れ て い る 。 d_type フ ィ ー ル ド は 、 Linux 以 外 で は 、 お も に BSD 系 の シ ス テ ム で の み 利 用 可 能 で あ る 。 残 り の フ ィ ー ル ド は 多 く の シ ス テ ム に 存 在 す る が 、 全 て の シ ス テ ム に 存 在 す る わ け で は な い 。 glibc で は 、 プ ロ グ ラ ム が POSIX.1 で 定 義 さ れ て い な い フ ィ ー ル ド が 利 用 で き る か を チ ェ ッ ク す る こ と が で き る 。 チ ェ ッ ク す る に は 、 マ ク ロ _DIRENT_HAVE_D_NAMLEN , _DIRENT_HAVE_D_RECLEN , _DIRENT_HAVE_D_OFF , _DIRENT_HAVE_D_TYPE が 定 義 さ れ て い る か を テ ス ト す れ ば よ い 。

d_name フ ィ ー ル ド

上 記 の dirent 構 造 体 の 定 義 は glibc の ヘ ッ ダ ー か ら の 引 用 で あ り 、 d_name フ ィ ー ル ド は 固 定 サ イ ズ と な っ て い る 。

警 告 : ア プ リ ケ ー シ ョ ン は 、 d_name フ ィ ー ル ド の サ イ ズ に 依 存 す べ き で は な い 。 POSIX で は こ の フ ィ ー ル ド は char d_name[] (サ イ ズ 不 定 の 文 字 配 列 ) と し て 規 定 し て お り 、 最 大 で 終 端 の ヌ ル バ イ ト ('\0') の 前 に NAME_MAX 文 字 が 入 る 。

POSIX.1 は 、 こ の フ ィ ー ル ド を 左 辺 値 と し て 使 用 す べ き で は な い と 明 記 し て い る 。 ま た 、 POSIX.1 で は 、 sizeof(d_name) の 使 用 は 間 違 い で あ り 、 代 わ り に strlen(d_name) を 使 用 す る よ う に 、 と の 注 記 も あ る (い く つ か の シ ス テ ム で は 、 こ の フ ィ ー ル ド は char d_name[1] ! と し て 定 義 さ れ て い る )。 こ の こ と は 、 d_name を 含 む レ コ ー ド の サ イ ズ を 取 得 す る た め に sizeof(struct dirent) を 使 用 す る こ と も 間 違 い で あ る こ と を 暗 に 示 し て い る 。

多 く の フ ァ イ ル シ ス テ ム で は 、

fpathconf(fd, _PC_NAME_MAX)

の 呼 び 出 し は 値 255 を 返 す が 、 い く つ か の フ ァ イ ル シ ス テ ム (例 え ば CIFS や Windows SMB サ ー バ ー な ど ) で は 、 (正 し い 動 作 な の だ が ) d_name で 返 さ れ る ヌ ル 終 端 さ れ た フ ァ イ ル 名 は 実 際 に は こ の サ イ ズ を 超 え る 場 合 が あ る 点 に 注 意 す る こ と 。 こ の よ う な 場 合 、 d_reclen フ ィ ー ル ド は 、 上 記 の glibc dirent 構 造 体 の サ イ ズ よ り も 大 き な 値 と な る 。

関 連 項 目

getdents (2), read (2), closedir (3), dirfd (3), ftw (3), offsetof (3), opendir (3), readdir_r (3), rewinddir (3), scandir (3), seekdir (3), telldir (3)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man-pages プ ロ ジ ェ ク ト の リ リ ー ス 5.10 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は https://www.kernel.org/doc/man-pages/ に 書 か れ て い る 。