path: root/usr/src/man/man3c/readdir.3c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2021 Oxide Computer Company
.\"
.Dd February 25, 2021
.Dt READDIR 3C
.Os
.Sh NAME
.Nm readdir ,
.Nm readdir_r
.Nd read directory
.Sh SYNOPSIS
.In sys/types.h
.In dirent.h
.Ft "struct dirent *"
.Fo readdir
.Fa "DIR *dirp"
.Fc
.Ft "struct dirent *"
.Fo readdir_r
.Fa "DIR *dirp"
.Fa "struct dirent *entry"
.Fc
.Ss Standard Conforming
.Fd #define _POSIX_PTHREAD_SEMANTICS
.Ft int
.Fo readdir_r
.Fa "DIR *restrict dirp"
.Fa "struct dirent *restrict entry"
.Fa "struct dirent **restrict result"
.Fc
.Sh DESCRIPTION
The type
.Ft DIR ,
which is defined in the header
.In dirent.h ,
represents a
.Em directory stream ,
which is an ordered sequence of all the directory entries in a particular
directory.
Directory entries represent files.
Files can be removed from a directory or added to a directory asynchronously
to the operation of
.Fn readdir
and
.Fn readdir_r .
.Ss Fn readdir
The
.Fn readdir
function returns a pointer to a structure representing the directory entry at
the current position in the directory stream specified by the argument
.Fa dirp ,
and positions the directory stream at the next entry.
It returns a null pointer upon reaching the end of the directory stream.
The structure
.Ft dirent
defined by the
.In dirent.h
header describes a directory entry.
.Pp
The
.Fn readdir
function will not return directory entries containing empty names.
If entries for
.No \&.
.Pq dot
.No \&..
.Pq dot-dot
exist, one entry will be returned for dot and one entry will be returned for
dot-dot; otherwise they will not be returned.
.Pp
The pointer returned by
.Fn readdir
points to data that can be overwritten by another call to
.Fn readdir
on the same directory stream.
It will not be overwritten by another call to
.Fn readdir
on a different directory stream.
The returned pointer will remain valid until the directory stream is
freed with a call to
.Xr closedir 3C .
It is safe to use
.Fn readdir
in a threaded application, so long as only one thread reads from the directory
stream at any given time.
.Pp
If a file is removed from or added to the directory after the most recent call
to
.Xr opendir 3C
or
.Xr rewinddir 3C ,
whether a subsequent call to
.Fn readdir
returns an entry for that file is unspecified.
.Pp
The
.Fn readdir
function can buffer several directory entries per actual read operation.
It marks for update the
.Ft st_atime
field of the directory each time the directory is actually read.
.Pp
After a call to
.Xr fork 2 ,
either the parent or child
.Pq but not both
can continue processing the directory stream using
.Fn readdir ,
.Xr rewinddir 3C ,
or
.Xr seekdir 3C .
If both the parent and child processes use these functions, the result is
undefined.
.Pp
If the entry names a symbolic link, the value of the
.Ft d_ino
member is unspecified.
.Ss Fn readdir_r
Unless the end of the directory stream has been reached or an error occurred,
the
.Fn readdir_r
function initializes the
.Ft dirent
structure referenced by
.Fa entry
to represent the directory entry at the current position in the directory
stream referred to by
.Fa dirp ,
and positions the directory stream at the next entry.
.Pp
The caller must allocate storage pointed to by
.Fa entry
to be large enough for a
.Ft dirent
structure with an array of
.Ft char
.Fa d_name
member containing at least
.Dv NAME_MAX
.Po
that is,
.Fo pathconf
.Fa directory ,
.Dv _PC_NAME_MAX
.Fc
plus one element.
.Po
.Dv _PC_NAME_MAX
is defined in
.In unistd.h
.Pc
.Pc
.Pp
While the
.Fn readdir_r function was originally added as a re-entrant version of
.Fn readdir ,
it is not recommended that
.Fn readdir_r
be used in new applications and existing software should instead use
.Fn readdir .
The
.Fn readdir_r
function has been deprecated in many systems.
Historically, the data returned from
.Fn readdir
was not specific to the directory stream making it unsafe in a multi-threaded
environment; however, that is no longer the case.
.Pp
The
.Fn readdir_r
function will not return directory entries containing empty names.
It is unspecified whether entries are returned for
.No \&.
.Pq dot
or
.No \&..
.Pq dot-dot .
.Pp
If a file is removed from or added to the directory after the most recent call
to
.Xr opendir 3C or
.Xr rewinddir 3C , whether a subsequent call to
.Fn readdir_r
returns an entry for that file is unspecified.
.Pp
The
.Fn readdir_r
function can buffer several directory entries per actual read operation.
It marks for update the
.Ft st_atime
field of the directory each time the directory is actually read.
.Pp
The standard-conforming version
.Po see
.Xr standards 5
.Pc
of the
.Fn readdir_r
function performs all of the actions described above for
.Fn readdir_r
and sets the pointer pointed to by
.Fa result .
If a directory entry is returned, the pointer will be set to the same value
as the
.Fa entry
argument; otherwise, it will be set to
.Dv NULL .
.Sh RETURN VALUES
Upon successful completion,
.Fn readdir
and the default
.Fn readdir_r
return a pointer to an object of type
.Ft struct dirent .
When an error is encountered, a null pointer is returned and
.Va errno
is set to indicate the error.
When the end of the directory is encountered, a null pointer is returned and
.Va errno
is not changed.
.Pp
The standard-conforming
.Fn readdir_r
returns
.Sy 0
if the end of the directory is encountered or a directory entry is stored in
the structure referenced by
.Fa entry .
Otherwise, an error number is returned to indicate the failure.
.Sh EXAMPLES
.Sy Example 1
Search the current directory for the entry
.Fa name .
.Pp
The following sample program will search the current directory for each of the
arguments supplied on the command line:
.Bd -literal
#include <sys/types.h>
#include <dirent.h>
#include <errno.h>
#include <stdio.h>
#include <strings.h>

static void
lookup(const char *arg)
{
        DIR *dirp;
        struct dirent *dp;

        if ((dirp = opendir(".")) == NULL) {
                perror("couldn't open '.'");
                return;
        }

        do {
                errno = 0;
                if ((dp = readdir(dirp)) != NULL) {
                        if (strcmp(dp->d_name, arg) != 0)
                                continue;

                        (void) printf("found %s\en", arg);
                        (void) closedir(dirp);
                        return;
                }
        } while (dp != NULL);

        if (errno != 0)
                perror("error reading directory");
        else
                (void) printf("failed to find %s\en", arg);
        (void) closedir(dirp);
}

int
main(int argc, char *argv[])
{
        int i;
        for (i = 1; i < argc; i++)
                lookup(argv[i]);
        return (0);
}
.Ed
.Sh ERRORS
The
.Fn readdir
and
.Fn readdir_r
functions will fail if:
.Bl -tag -width Er
.It Er EOVERFLOW
One of the values in the structure to be returned cannot be represented
correctly.
.El
.Pp
The
.Fn readdir
and
.Fn readdir_r
functions may fail if:
.Bl -tag -width Er
.It Er EBADF
The
.Fa dirp
argument does not refer to an open directory stream.
.It Er ENOENT
The current position of the directory stream is invalid.
.El
.Sh USAGE
The
.Fn readdir
and
.Fn readdir_r
functions should be used in conjunction with
.Xr opendir 3C ,
.Xr closedir 3C ,
and
.Xr rewinddir 3C
to examine the contents of the directory.
Since
.Fn readdir
and the default
.Fn readdir_r
return a null pointer both at the end of the directory and on error, an
application wanting to check for error situations should set
.Va errno
to 0 before calling either of these functions.
If
.Va errno
is set to non-zero on return, an error occurred.
.Pp
The standard-conforming
.Fn readdir_r
returns the error number if an error occurred.
It returns 0 on success
.Pq including reaching the end of the directory stream .
.Pp
The
.Fn readdir
and
.Fn readdir_r
functions have transitional interfaces for 64-bit file offsets.
See
.Xr lf64 5 .
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
The
.Fn readdir
function is
.Sy Unsafe ;
however, it is
.Sy Safe
if different directory streams are used concurrently.
The
.Fn readdir_r
function is
.Sy Safe .
.Sh SEE ALSO
.Xr fork 2 ,
.Xr lstat 2 ,
.Xr symlink 2 ,
.Xr Intro 3 ,
.Xr closedir 3C ,
.Xr opendir 3C ,
.Xr rewinddir 3C ,
.Xr scandir 3C ,
.Xr seekdir 3C ,
.Xr attributes 5 ,
.Xr lf64 5 ,
.Xr standards 5
.Sh NOTES
When compiling multithreaded programs, see the
.Sy MULTITHREADED APPLICATIONS
section of
.Xr Intro 3 .
.Pp
Solaris 2.4 and earlier releases provided a
.Fn readdir_r
interface as specified in POSIX.1c Draft 6.
The final POSIX.1c standard changed the interface as described above.
Support for the Draft 6 interface is provided for compatibility only.
New applications and libraries should use the standard-conforming interface,
though preferably
.Fn readdir .
.Pp
For POSIX.1c-conforming applications, the
.Dv _POSIX_PTHREAD_SEMANTICS
and
.Dv _REENTRANT
flags are automatically turned on by defining the
.Dv _POSIX_C_SOURCE
flag with a value >= 199506L.