\"      $NetBSD: directory.3,v 1.43 2021/02/17 23:51:04 dholland Exp $
\"
\" 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
In 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.
Bl -tag -width XXX
It 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 .
It 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.
Pp
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 .
It 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 .
Pp
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.
It 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.
Pp
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.
It Fn telldir "dirp"
The
Fn telldir
function returns the current location associated
with the directory stream specified by
Fa dirp .
Pp
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.
It 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.
Pp
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.
It 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
Pp
If
Fa dirp
does not refer to a valid directory stream, the behavior is undefined.
It 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.
It 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 .
Pp
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:
Bd -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.
Pp
The following additional remarks can be noted from the
St -p1003.1-2008
standard.
Bl -bullet -offset 2n
It
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.
It
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.
It
If directory streams are not implemented by using file descriptors,
functions such as
Fn dirfd
may fail with
Er ENOTSUP .
It
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.
It
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.
It
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
Bx 4.2 .
The
Fn fdopendir
function appeared in
Nx 6.0 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.