.\" 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$
.Dd June 4, 1993
.Dt DIRECTORY 3
.Os BSD 4.2
.Sh 名称
.Nm opendir ,
.Nm readdir ,
.Nm telldir ,
.Nm seekdir ,
.Nm rewinddir ,
.Nm closedir ,
.Nm dirfd
.Nd ディレクトリ操作
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <dirent.h>
.Ft DIR *
.Fn opendir "const char *filename"
.Ft struct dirent *
.Fn readdir "DIR *dirp"
.Ft long
.Fn telldir "const 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 telldir
関数は、名前の付いた
.Em ディレクトリストリーム
に対応する現在の位置を返します。
.Fn telldir
が返す値が良いのは、派生させられる元となった
.Dv DIR
ポインタ
.Fa dirp
の寿命の間だけです。ディレクトリが閉じられ再び開かれると、
.Fn telldir
が返した以前の値はもはや有効ではありません。
.Pp
.Fn seekdir
関数は、
.Em ディレクトリストリーム
への次の
.Fn readdir
操作の位置を設定します。新しい位置は、
.Fn telldir
操作が実行されたときの
.Em ディレクトリストリーム
と対応付けられたものに戻ります。
.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
で現れました。
