EN JA
DIRECTORY(3)
DIRECTORY(3) FreeBSD Library Functions Manual DIRECTORY(3)

名称

opendir, fdopendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir, fdclosedir, dirfdディレクトリ操作

ライブラリ

Standard C Library (libc, -lc)

書式

#include < sys/types.h>
#include < dirent.h>

DIR *
opendir( const char *filename);

DIR *
fdopendir( int fd);

struct dirent *
readdir( DIR *dirp);

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

long
telldir( DIR *dirp);

void
seekdir( DIR *dirp, long loc);

void
rewinddir( DIR *dirp);

int
closedir( DIR *dirp);

int
fdclosedir( DIR *dirp);

int
dirfd( DIR *dirp);

解説

opendir() 関数は、 filename によって指定されたディレクトリをオープンし、 ディレクトリストリーム をそれに関連付けし、続く操作で ディレクトリストリーム を識別するために使用されるポインタを返します。 filename にアクセスすることができないか、またはすべてのものを保持するために十分なメモリを malloc(3) することができないなら、ポインタ NULL が返されます。

fdopendir() 関数は、ディレクトリが名前でなくファイル記述子 fd によって指定されることを除いて、 opendir() 関数と同等です。呼び出し時点でファイル記述子に関連しているファイルオフセットは、どのエントリが返されるかを決定します。

fdopendir() から成功して返るときに、ファイル記述子がシステムの制御の下にあり、ファイル記述子をクローズするか、または closedir(), readdir(), readdir_r() または rewinddir() を用いる以外の関連記述の状態を変更するなんらかの試みが行われるなら、振る舞いは、未定義です。 closedir() を呼び出すとき、ファイル記述子は、クローズされます。 FD_CLOEXEC フラグは、 fdopendir() への成功した呼び出しによってファイル記述子で設定されます。

readdir() 関数は、次のディレクトリエントリへのポインタを返します。ディレクトリの終りに到達するか、またはエラーで NULL を返します。エラーのイベントで、 errno は、 getdirentries(2) システムコールのための文書化された値のいずれかが設定されます。

readdir_r() 関数は、 readdir() と同じ機能を提供しますが、呼び出し側は、結果を格納するためのディレクトリ entry バッファを提供しなければなりません。読み込みが成功するなら、 result は、 entry を指します。ディレクトリの終りに到着するとき、 result は、 NULL に設定されます。 readdir_r() 関数は、成功すれば、0 を返すか、または失敗を示すためにエラー番号を返します。

telldir() 関数は、指定された ディレクトリストリーム に関連した現在の位置を表わすトークンを返します。 telldir() によって返された値は、それらに由来する DIR ポインタ dirp の存続期間のみ有効です。ディレクトリがクローズされ、次に、再オープンされるなら、 telldir() によって返された以前の値は、もはや有効ではありません。

seekdir() 関数は、 ディレクトリストリーム で次の readdir() 操作の位置を設定します。新しい位置は、 telldir() 操作が実行されたとき、 ディレクトリストリーム と関連付けられた位置になります。 telldir() によって返されたトークンに関連した状態は、それが seekdir() に渡されたとき、解放されます。再び同じ位置に返りたいなら、別の telldir() 呼び出しで新しいトークンを作成しなければなりません。

rewinddir() 関数は、指定された ディレクトリストリーム の位置をディレクトリの始めにリセットします。

closedir() 関数は、指定された ディレクトリストリーム をクローズし、成功すれば、0 を返し、 dirp ポインタに関連した構造体を解放します。失敗すれば、-1 が返され、グローバル変数 errno は、エラーを示す値が設定されます。

fdclosedir() 関数は、この関数が、ディレクトリストリームをクローズする代わりにディレクトリファイルの記述子を返すことを除いて、 closedir() 関数と同等です。

dirfd() 関数は、指定された ディレクトリストリーム に関連した整数のファイル記述子 ( open(2) を参照) を返します。

エントリ ``name'' のディレクトリを検索するサンプルコードは、次の通りです:

dirp = opendir("."); 
if (dirp == NULL) 
 return (ERROR); 
len = strlen(name); 
while ((dp = readdir(dirp)) != NULL) { 
 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) { 
  (void)closedir(dirp); 
  return (FOUND); 
 } 
} 
(void)closedir(dirp); 
return (NOT_FOUND);

歴史

opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir() と dirfd() 関数は、 4.2BSD で登場しました。 fdopendir() 関数は、 FreeBSD 8.0 で登場しました。 fdclosedir() 関数は、 FreeBSD 10.0 で登場しました。

バグ

seekdir() を呼び出すとき、 telldir() トークンの失効は、非標準です。
August 18, 2013 FreeBSD