Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       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_named_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) を参照。

       ┌─────────────────┬───────────────┬──────────────────────────┐
       │インターフェース属性                       │
       ├─────────────────┼───────────────┼──────────────────────────┤
       │readdir()        │ Thread safety │ MT-Unsafe race:dirstream │
       └─────────────────┴───────────────┴──────────────────────────┘

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

                                            2019-03-06                                 READDIR(3)