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. 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
.Dd February 17, 2021 .Dt DIRECTORY 3 .Os .Sh NAME .Nm fdopendir , .Nm opendir , .Nm readdir , .Nm readdir_r , .Nm telldir , .Nm seekdir , .Nm rewinddir , .Nm closedir , .Nm dirfd .Nd directory operations .Sh LIBRARY .Lb libc .Sh SYNOPSIS n dirent.h .Ft DIR * .Fn opendir "const char *filename" .Ft DIR * .Fn fdopendir "int fd" .Ft struct dirent * .Fn readdir "DIR *dirp" .Ft int .Fn readdir_r "DIR * restrict dirp" "struct dirent * restrict entry" "struct dirent ** restrict 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 DESCRIPTION The type .Vt DIR represents a directory stream; an ordered sequence of all directory entries in a particular directory. The purpose of the .Vt DIR structure is similar to that of the .Vt FILE structure maintained by the .Xr stdio 3 library functions. .Sh FUNCTIONS The following standard directory operations are defined. l -tag -width XXX t Fn opendir "filename" The .Fn opendir function opens the directory named by .Fa filename and associates a directory stream with it. The directory stream is positioned at the first entry. Upon successful completion, a pointer to .Vt DIR type is returned. Otherwise, .Fn opendir returns .Dv NULL . t Fn fdopendir "fd" The .Fn fdopendir function associates a directory stream with the directory file descriptor .Fa fd . The file offset associated with .Fa fd at the time of the call determines which entries are returned.
p Upon failure, .Fn fdopendir returns .Dv NULL . Otherwise the file descriptor is under the control of the system, and if any attempt is made to close the file descriptor, or to modify the state of the associated description, other than by means of .Fn closedir , .Fn readdir , .Fn readdir_r , .Fn rewinddir , the behavior is undefined. The file descriptor can be closed by calling .Fn closedir . t Fn readdir "dirp" The .Fn readdir function returns a pointer to the directory entry at the current position in the directory stream specified by .Fa dirp , and positions the directory stream at the next entry. It returns .Dv NULL upon reaching the end of the directory or detecting an invalid .Fn seekdir operation. The returned structure is described in .Xr dirent 3 .
p The returned pointer to the .Em dirent structure points to data which may be overwritten by another call to .Fn readdir on the same directory stream. This data is not however overwritten by another call to .Fn readdir on a different directory stream. t Fn readdir_r "dirp" "entry" "result" The .Fn readdir_r function provides the same functionality as .Fn readdir , but the caller must provide a directory .Fa entry buffer to store the results in. If the read succeeds, .Fa result is pointed at the .Fa entry ; upon reaching the end of the directory .Fa result is set to .Dv NULL . The .Fn readdir_r function returns 0 on success or an error number to indicate failure.
p Like .Fn readdir , the .Fn readdir_r function may buffer several directory entries per actual read operation. Both functions mark for update the .Em st_atime field (see .Xr stat 2 ) of the directory each time the directory is actually read. t Fn telldir "dirp" The .Fn telldir function returns the current location associated with the directory stream specified by .Fa dirp .
p If the most recent operation on the particular directory stream was a .Fn seekdir , the directory position returned from .Fn telldir is the same as .Fa loc supplied as an argument to the .Fn seekdir call. t Fn seekdir "dirp" "loc" The .Fn seekdir function sets the position of the next .Fn readdir operation on the directory stream specified by .Fa dirp . The value of .Fa loc should come from a previous call to .Fn telldir using the same directory stream.
p
The new position reverts to the one associated
with the directory stream when the
.Fn telldir
operation was performed.
Values returned by
.Fn telldir
are good only for the lifetime of the
.Vt DIR
pointer,
.Fa dirp ,
from which they are derived.
If the directory is closed and then reopened, the
.Fn telldir
value cannot be re-used.
t Fn rewinddir "dirp" The
.Fn rewinddir
function resets the position of the named directory
stream to the beginning of the directory.
It also causes the directory stream to refer to the
current state of the corresponding directory, as if a call to
.Fn opendir
was made.
It is not specified whether this refers to the ``corresponding directory''
by name or by underlying object.
(These can differ if
.Xr rename 2
has been used.)
Note: currently the underlying fd is reopened if and only if
__DTF_READALL is in effect, which is true for union mounts and
nfs; documenting that exactly seems inadvisable since it might
change. -- dholland 20210217
p If .Fa dirp does not refer to a valid directory stream, the behavior is undefined. t Fn closedir "dirp" The .Fn closedir function closes the directory stream and frees the structure associated with the .Fa dirp pointer, returning 0 on success and -1 on failure. t Fn dirfd "dirp" The .Fn dirfd function returns the integer file descriptor associated with the directory stream specified by .Fa dirp . Upon failure, .Fn dirfd returns -1. The returned file descriptor should not be closed by .Xr close 2 , it will be released when .Fa dirp is closed with .Fn closedir .
p The rationale of .Fn dirfd is to provide a mechanism by which a file descriptor can be obtained for the use of the .Xr fchdir 2 function. .El .Sh EXAMPLES Sample code which searches a directory for entry .Dq name is: d -literal -offset indent len = strlen(name); dirp = opendir("."); if (dirp != NULL) { 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); .Ed .Sh COMPATIBILITY The described directory operations have traditionally been problematic in terms of portability. A good example is the semantics of .Sq . (dot) and .Sq .. (dot-dot). Based on historical implementations, the rules about file descriptors apply to directory streams as well. The .St -p1003.1-2008 standard no longer mandates that directory streams be implemented by using file descriptors.
p
The following additional remarks can be noted from the
.St -p1003.1-2008
standard.
l -bullet -offset 2n t If the type
.Vt DIR
is implemented using a file descriptor,
like in
.Nx ,
applications should be able to open only
.Dv OPEN_MAX
files and directories.
Otherwise the limit is left as unspecified.
t When a file descriptor is used to implement the directory stream, the
.Fn closedir
function behaves as if the
.Dv FD_CLOEXEC
had been set for the file descriptor.
In other words, it is mandatory that
.Fn closedir
deallocates the file descriptor.
t If directory streams are not implemented by using file descriptors,
functions such as
.Fn dirfd
may fail with
.Er ENOTSUP .
t If a file is removed from or added to the directory
after the most recent call to
.Fn opendir
or
.Fn rewinddir ,
it is unspecified whether a subsequent call to
.Fn readdir
returns an entry for that file.
t When using the function
.Fn seekdir ,
note that if the value of
.Fa loc
was not obtained from an earlier call to
.Fn telldir ,
or if a call to
.Fn rewinddir
occurred between the calls to
.Fn telldir
and
.Fn seekdir ,
the results of any subsequent call to
.Fn readdir
are unspecified, possibly resulting in undefined behavior.
t After a call to
.Xr fork 2 ,
either the parent or child (but not both) can continue processing the
directory stream using
.Fn readdir ,
.Fn rewinddir ,
or
.Fn seekdir .
However, if both the parent and child processes use these functions,
the result is undefined.
.El
.Sh ERRORS
XXX: The errors should be enumerated.
All described functions may set
.Vt errno
to indicate the error.
.Sh SEE ALSO
.Xr close 2 ,
.Xr lseek 2 ,
.Xr open 2 ,
.Xr read 2 ,
.Xr dirent 3
.Sh STANDARDS
The
.Fn opendir ,
.Fn readdir ,
.Fn rewinddir
and
.Fn closedir
functions conform to
.St -p1003.1-90 .
The other functions conform to
.St -p1003.1-2008 .
.Sh HISTORY
The
.Fn opendir ,
.Fn readdir ,
.Fn telldir ,
.Fn seekdir ,
.Fn rewinddir ,
.Fn closedir ,
and
.Fn dirfd
functions appeared in
x 4.2 . The
.Fn fdopendir
function appeared in
.Nx 6.0 .
Indexes created Tue Sep 23 14:10:03 GMT 2025