readdir_r

名前

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

書式

#include <dirent.h>

int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);

readdir_r():

説明

この関数は非推奨である。代わりに readdir(3) を使用すること。 readdir_r() 関数は readdir(3) のリエントラント版として導入された。この関数はディレクトリストリーム dirp から次のディレクトリエントリーを読み込み、 entry が指す呼び出し元が割り当てたバッファーにそのエントリーを格納して返す。 dirent 構造体の詳細は readdir(3) を参照。 結果を返すバッファへのポインターが *result に格納される。ディレクトリストリームの末尾に達した場合は、NULL が代わりに *result で返される。 アプリケーションでは readdir_r() の代わりに readdir(3) を使用することを推奨する。さらに、glibc 2.24 以降では readdir_r() は非推奨となっている。理由は以下の通りである。

*

NAME_MAX が未定義のシステムでは、 readdir_r() の呼び出しは安全ではない。このインターフェースでは、呼び出し元がディレクトリエントリーを返す際に使用されるバッファの長さを指定することができないからである。

*

いくつかのシステムでは、 readdir_r() は非常に長い名前のディレクトリエントリーを読み込むことができない。 glibc の実装ではこのような名前に遭遇した場合、 readdir_r() は 最後のディレクトリエントリーを読み込んだ後 エラー ENAMETOOLONG で失敗する。他のいくつかのシステムでは、 readdir_r() が成功ステータスを返しても、返された d_name フィールドがヌル終端されていなかったり、文字列が途中までで切り詰められていたりすることがある。

*

現在の POSIX.1 標準 (POSIX.1-2008) では、 readdir(3) がスレッドセーフであることは求められていない。しかしながら、最近の実装 (glibc による実装も含む) では、異なるディレクトリストリームに対する readdir(3) の同時並行の呼び出しはスレッドセーフである。したがって、マルチスレッドプログラムにおいて readdir_r() の使用は不要である。複数のスレッドが同じディレクトリストリームから読み込みを行う必要がある場合も、上記で挙げた理由から、非推奨の readdir_r() 関数を使用するよりも、外部同期を用いた readdir(3) を使う方が推奨される。

*

POSIX.1 の将来のバージョンでは、 readdir_r() は廃止予定 (obsolete) となり、 readdir(3) は異なるディレクトリストリームに対して同時に使用された際にスレッドセーフであることが必須となる予定である。

返り値

成功すると、 readdir_r() 関数は 0 を返す。 エラーの場合、(「エラー」の節のリストに載っている) 正のエラー番号を返す。 ディレクトリストリームの末尾に達した場合、 readdir_r() は返り値として 0 を返し、 *result に NULL を格納する。

エラー

EBADF

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

ENAMETOOLONG

読み込むには名前が長過ぎるディレクトリエントリーに遭遇した。

属性

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

インターフェース	属性	値
readdir_r()	Thread safety	MT-Safe

準拠

POSIX.1-2001, POSIX.1-2008.

関連項目

readdir(3)

この文書について

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