日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
DIRECTORY(3) FreeBSD ライブラリ関数マニュアル DIRECTORY(3)
名称
opendir, fdopendir, readdir, readdir_r, telldir, seekdir, rewinddir,
closedir, fdclosedir, dirfd -- ディレクトリ操作
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#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);
解説
readdir_r() インタフェースは、{NAME_MAX} が、固定された値ではないので、そ
れを正しく使用することができないので、推奨されません。
opendir() 関数は、filename によって指定されたディレクトリをオープンし、
ディレクトリストリームをそれに関連付けし、続く操作でディレクトリストリー
ムを識別するために使用されるポインタを返します。filename にアクセスするこ
とができないか、またはすべてのものを保持するために十分なメモリを
malloc(3) することができないなら、ポインタ NULL が返されます。
fdopendir() 関数は、ディレクトリが名前でなくファイル記述子 fd によって指
定されることを除いて、opendir() 関数と同等です。呼び出し時点でファイル記
述子に関連しているファイルオフセットは、どのエントリが返されるかを決定し
ます。
fdopendir() から成功して返るときに、ファイル記述子がシステムの制御の下に
あり、ファイル記述子をクローズするか、または closedir(), readdir(),
readdir_r() または rewinddir() を用いる以外の関連記述の状態を変更するなん
らかの試みが行われるなら、振る舞いは、未定義です。closedir() を呼び出すと
き、ファイル記述子は、クローズされます。FD_CLOEXEC フラグは、fdopendir()
への成功した呼び出しによってファイル記述子で設定されます。
readdir() 関数は、次のディレクトリエントリへのポインタを返します。ディレ
クトリエントリは、同じディレクトリストリームで、readdir() または
closedir() への次の呼び出しまで有効であり続けます。関数は、ディレクトリの
終わりに達するか、またはエラーで NULL を返します。エラーのイベントで、
errno は、getdirentries(2) システムコールのための文書化された値のいずれか
が設定されます。
readdir_r() 関数は、readdir() と同じ機能を提供しますが、呼び出し側は、結
果を格納するためのディレクトリ entry バッファを提供しなければなりません。
バッファは、{NAME_MAX} +1 の要素がある d_name 配列で struct dirent のため
に十分に大きくなければなりません。読み込みが成功するなら、result は、
entry を指します。ディレクトリの終りに到着するとき、result は、NULL に設
定されます。readdir_r() 関数は、成功すれば、0 を返すか、または失敗を示す
ためにエラー番号を返します。
telldir() 関数は、指定されたディレクトリストリームに関連した現在の位置を
表わすトークンを返します。telldir() によって返された値は、それらに由来す
る DIR ポインタ dirp の存続期間のみ有効です。ディレクトリがクローズされ、
次に、再オープンされるなら、telldir() によって返された以前の値は、もはや
有効ではありません。また、telldir() によって返された値は、rewinddir() へ
の呼び出しによって無効にされます。
seekdir() 関数は、ディレクトリストリームで次の readdir() 操作の位置を設定
します。新しい位置は、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() 関数は、次の場合に失敗します:
[EACCES] 検索パーミッションが、filename のパス接頭辞の構成要素
のための拒否されるか、または読み込みパーミッションが、
filename のために拒否されます。
[ELOOP] filename 引数の解決の間に遭遇するシンボリックリンクに
ループが存在します。
[ENAMETOOLONG] filename 引数の長さが、{PATH_MAX} を超えるか、パス名の
構成要素が {NAME_MAX} より長くなっています。
[ENOENT] filename の構成要素が、既存のディレクトリの名前でない
か、または filename が、空文字列です。
[ENOTDIR] filename の構成要素が、ディレクトリではありません。
fdopendir() 関数は、次の場合に失敗します:
[EBADF] fd 引数が、読み込みのためにオープンされた有効なファイ
ル記述子ではありません。
[ENOTDIR] 記述子 fd が、ディレクトリに関連付けられていません。
また readdir() と readdir_r() 関数は、失敗して、ルーチン getdents(2) のた
めに指定されたエラーのいずれかのために errno を設定します。
telldir() 関数は、また、失敗して、ルーチン realloc(3) のために指定された
エラーのいずれかのために errno を設定します。
closedir() 関数は、また、失敗して、ルーチン close(2) のために指定されたエ
ラーのいずれかのために errno を設定します。
関連項目
close(2), lseek(2), open(2), read(2), dir(5)
規格
closedir(), dirfd(), fdopendir(), opendir(), readdir(), readdir_r(),
rewinddir(), seekdir() と telldir() 関数は、IEEE Std 1003.1-2008
(``POSIX.1'') に適合するはずです。fdclosedir() 関数と struct dirent の
d_off, d_reclen と d_type フィールドは、非標準であり、移植性のあるプログ
ラムで使用するべきではありません。
歴史
opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir() と
dirfd() 関数は、4.2BSD で登場しました。fdopendir() 関数は、FreeBSD 8.0 で
登場しました。fdclosedir() 関数は、FreeBSD 10.0 で登場しました。
バグ
telldir() と seekdir() の振る舞いは、平行なアンリンクが起こり、ディレクト
リが、1 ページより大きいなら、悪くなる可能性があります。最後の readdir()
は、実行された、その最後の readdir() と同じ値を返すために、常に、正しい位
置を設定する直前に telldir() によって与えられた位置に seekdir() すること
を保証するためのコードがあります。これは、"呼び込まれた最後のエントリを押
し戻す" ことを望んでいるいくつかのアプリケーションにとって十分です、例え
ば、Samba。ディレクトリの最初以外のあらゆる他の位置にシークして戻ること
は、削除が存在するなら、予期されない振る舞いの結果となります。この状況
が、getdirentries() と VFS に変更で改善することは、望まれます。
FreeBSD 13.2 August 1, 2020 FreeBSD 13.2