.\" Copyright (c) 1983, 1991, 1993
.\"     The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"     This product includes software developed by the University of
.\"     California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)directory.3 8.1 (Berkeley) 6/4/93
.\" %FreeBSD: src/lib/libc/gen/directory.3,v 1.7.2.4 2001/12/14 18:33:50 ru Exp %
.\"
.\" $FreeBSD$
.Dd June 4, 1993
.Dt DIRECTORY 3
.Os
.Sh 名称
.Nm opendir ,
.Nm readdir ,
.Nm readdir_r ,
.Nm telldir ,
.Nm seekdir ,
.Nm rewinddir ,
.Nm closedir ,
.Nm dirfd
.Nd ディレクトリ操作
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In dirent.h
.Ft DIR *
.Fn opendir "const char *filename"
.Ft struct dirent *
.Fn readdir "DIR *dirp"
.Ft int
.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
.Ft long
.Fn telldir "DIR *dirp"
.Ft void
.Fn seekdir "DIR *dirp" "long  loc"
.Ft void
.Fn rewinddir "DIR *dirp"
.Ft int
.Fn closedir "DIR *dirp"
.Ft int
.Fn dirfd "DIR *dirp"
.Sh 解説
.Fn opendir
関数は、
.Fa filename
で指定されたディレクトリを開き、
.Em ディレクトリストリーム
をそれに対応させ、後続の操作で
.Em ディレクトリストリーム
を識別するのに使用するポインタを返します。
.Fa filename
にアクセスできない場合、またはすべてのものを保持するのに十分なメモリを
.Xr malloc 3
できない場合は、ポインタ
.Dv NULL
が返されます。
.Pp
.Fn readdir
関数は、次のディレクトリエントリを指すポインタを返します。
この関数は、ディレクトリの末尾に到達するか、または無効な
.Fn seekdir
操作を検出すると
.Dv NULL
を返します。
.Pp
.Fn readdir_r
は、
.Fn readdir
と同様の機能を提供しますが、
呼び出し元は結果を格納するためのディレクトリ
.Fa entry
バッファを提供しなければなりません。
読み込みが成功すると
.Fa result
は
.Fa entry
を指し、ディレクトリの末尾に達すると
.Fa result
は
.Dv NULL
に設定されます。
.Fn readdir_r
は、成功した場合 0 を返し、そうでなければ失敗を示すエラーナンバを返します。
.Pp
.Fn telldir
関数は、指定された
.Em ディレクトリストリーム
に関連付けられている現在の位置を返します。
.Fn telldir
が返す値が有効なのは、その値が引き出された元の
.Dv DIR
ポインタ
.Fa dirp
が生きている間だけです。
ディレクトリが閉じられ再び開かれると、
.Fn telldir
が返した以前の値はもはや有効ではありません。
.Pp
.Fn seekdir
関数は、その
.Em ディレクトリストリーム
に対する次の
.Fn readdir
操作の位置を設定します。
新しい位置は、その
.Em ディレクトリストリーム
と関連付けられているもので、
.Fn telldir
操作が実行されたときに返されるものです。
.Pp
.Fn rewinddir
関数は、指定された
.Em ディレクトリストリーム
の位置をそのディレクトリの先頭に戻します。
.Pp
.Fn closedir
関数は、指定された
.Em ディレクトリストリーム
を閉じ、
.Fa dirp
ポインタに関連付けられた構造体を解放します。
処理が成功した場合は 0 を返します。
処理が失敗すると \-1 が返され、エラーを示ためにグローバル変数
.Va errno
が設定されます。
.Pp
.Fn dirfd
関数は、指定された
.Em ディレクトリストリーム
に関連付けられた整数のファイル記述子を返します。
.Xr open 2
を参照してください。
.Pp
ディレクトリでエントリ ``name'' を検索するサンプルコードは次のとおりです。
.Bd -literal -offset indent
len = strlen(name);
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL)
        if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
                (void)closedir(dirp);
                return FOUND;
        }
(void)closedir(dirp);
return NOT_FOUND;
.Pp
.Sh 関連項目
.Xr close 2 ,
.Xr lseek 2 ,
.Xr open 2 ,
.Xr read 2 ,
.Xr dir 5
.Pp
.Sh 歴史
.Fn opendir ,
.Fn readdir ,
.Fn telldir ,
.Fn seekdir ,
.Fn rewinddir ,
.Fn closedir
および
.Fn dirfd
の各関数は
.Bx 4.2
で登場しました。