readdir.3p (10344B)
- '\" et
- .TH READDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- readdir,
- readdir_r
- \(em read a directory
- .SH SYNOPSIS
- .LP
- .nf
- #include <dirent.h>
- .P
- struct dirent *readdir(DIR *\fIdirp\fP);
- int readdir_r(DIR *restrict \fIdirp\fP, struct dirent *restrict \fIentry\fP,
- struct dirent **restrict \fIresult\fP);
- .fi
- .SH DESCRIPTION
- The type
- .BR DIR ,
- which is defined in the
- .IR <dirent.h>
- header, represents a
- .IR "directory stream" ,
- which is an ordered sequence of all the directory entries in a
- particular directory. Directory entries represent files; files may be
- removed from a directory or added to a directory asynchronously to the
- operation of
- \fIreaddir\fR().
- .P
- The
- \fIreaddir\fR()
- function shall return a pointer to a structure representing the
- directory entry at the current position in the directory stream
- specified by the argument
- .IR dirp ,
- and position the directory stream at the next entry. It shall return a
- null pointer upon reaching the end of the directory stream. The
- structure
- .BR dirent
- defined in the
- .IR <dirent.h>
- header describes a directory entry. The value of the structure's
- .IR d_ino
- member shall be set to the file serial number of the file named by the
- .IR d_name
- member. If the
- .IR d_name
- member names a symbolic link, the value of the
- .IR d_ino
- member shall be set to the file serial number of the symbolic link itself.
- .P
- The
- \fIreaddir\fR()
- function shall not return directory entries containing empty names. If
- entries for dot or dot-dot exist, one entry shall be returned for dot
- and one entry shall be returned for dot-dot; otherwise, they shall not
- be returned.
- .P
- The application shall not modify the structure to which the return
- value of
- \fIreaddir\fR()
- points, nor any storage areas pointed to by pointers within the
- structure. The returned pointer, and pointers within the structure,
- might be invalidated or the structure or the storage areas might be
- overwritten by a subsequent call to
- \fIreaddir\fR()
- on the same directory stream. They shall not be affected by a call to
- \fIreaddir\fR()
- on a different directory stream. The returned pointer, and pointers
- within the structure, might also be invalidated if the calling thread
- is terminated.
- .P
- If a file is removed from or added to the directory after the most
- recent call to
- \fIopendir\fR()
- or
- \fIrewinddir\fR(),
- whether a subsequent call to
- \fIreaddir\fR()
- returns an entry for that file is unspecified.
- .P
- The
- \fIreaddir\fR()
- function may buffer several directory entries per actual read
- operation;
- \fIreaddir\fR()
- shall mark for update the last data access timestamp
- of the directory each time the directory is actually read.
- .P
- After a call to
- \fIfork\fR(),
- either the parent or child (but not both) may continue processing the
- directory stream using
- \fIreaddir\fR(),
- \fIrewinddir\fR(),
- or
- \fIseekdir\fR().
- If both the parent and child processes use these functions, the result
- is undefined.
- .P
- The
- \fIreaddir\fR()
- function need not be thread-safe.
- .P
- Applications wishing to check for error situations should set
- .IR errno
- to 0 before calling
- \fIreaddir\fR().
- If
- .IR errno
- is set to non-zero on return, an error occurred.
- .P
- The
- \fIreaddir_r\fR()
- function shall initialize the
- .BR dirent
- structure referenced by
- .IR entry
- to represent the directory entry at the current position in the
- directory stream referred to by
- .IR dirp ,
- store a pointer to this structure at the location referenced by
- .IR result ,
- and position the directory stream at the next entry.
- .P
- The storage pointed to by
- .IR entry
- shall be large enough for a
- .BR dirent
- with an array of
- .BR char
- .IR d_name
- members containing at least
- {NAME_MAX}+1
- elements.
- .P
- Upon successful return, the pointer returned at *\fIresult\fP shall have
- the same value as the argument
- .IR entry .
- Upon reaching the end of the directory stream, this pointer shall
- have the value NULL.
- .P
- The
- \fIreaddir_r\fR()
- function shall not return directory entries containing empty names.
- .P
- If a file is removed from or added to the directory after the most
- recent call to
- \fIopendir\fR()
- or
- \fIrewinddir\fR(),
- whether a subsequent call to
- \fIreaddir_r\fR()
- returns an entry for that file is unspecified.
- .P
- The
- \fIreaddir_r\fR()
- function may buffer several directory entries per actual read
- operation;
- \fIreaddir_r\fR()
- shall mark for update the last data access timestamp of the directory
- each time the directory is actually read.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIreaddir\fR()
- shall return a pointer to an object of type
- .BR "struct dirent" .
- When an error is encountered, a null pointer shall be returned and
- .IR errno
- shall be set to indicate the error. When the end of the directory is
- encountered, a null pointer shall be returned and
- .IR errno
- is not changed.
- .P
- If successful, the
- \fIreaddir_r\fR()
- function shall return zero; otherwise, an error number shall be
- returned to indicate the error.
- .SH ERRORS
- These functions shall fail if:
- .TP
- .BR EOVERFLOW
- One of the values in the structure to be returned cannot be represented
- correctly.
- .P
- These functions may fail if:
- .TP
- .BR EBADF
- The
- .IR dirp
- argument does not refer to an open directory stream.
- .TP
- .BR ENOENT
- The current position of the directory stream is invalid.
- .LP
- .IR "The following sections are informative."
- .SH "EXAMPLES"
- The following sample program searches the current directory for
- each of the arguments supplied on the command line.
- .sp
- .RS 4
- .nf
- #include <dirent.h>
- #include <errno.h>
- #include <stdio.h>
- #include <string.h>
- .P
- static void lookup(const char *arg)
- {
- DIR *dirp;
- struct dirent *dp;
- .P
- if ((dirp = opendir(".")) == NULL) {
- perror("couldn\(aqt open \(aq.\(aq");
- return;
- }
- .P
- do {
- errno = 0;
- if ((dp = readdir(dirp)) != NULL) {
- if (strcmp(dp->d_name, arg) != 0)
- continue;
- .P
- (void) printf("found %s\en", arg);
- (void) closedir(dirp);
- return;
- .P
- }
- } while (dp != NULL);
- .P
- if (errno != 0)
- perror("error reading directory");
- else
- (void) printf("failed to find %s\en", arg);
- (void) closedir(dirp);
- return;
- }
- .P
- int main(int argc, char *argv[])
- {
- int i;
- for (i = 1; i < argc; i++)
- lookup(argv[i]);
- return (0);
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- The
- \fIreaddir\fR()
- function should be used in conjunction with
- \fIopendir\fR(),
- \fIclosedir\fR(),
- and
- \fIrewinddir\fR()
- to examine the contents of the directory.
- .P
- The
- \fIreaddir_r\fR()
- function is thread-safe and shall return values in a user-supplied
- buffer instead of possibly using a static data area that may be
- overwritten by each call.
- .SH RATIONALE
- The returned value of
- \fIreaddir\fR()
- merely \fIrepresents\fP a directory entry. No equivalence should be
- inferred.
- .P
- Historical implementations of
- \fIreaddir\fR()
- obtain multiple directory entries on a single read operation, which
- permits subsequent
- \fIreaddir\fR()
- operations to operate from the buffered information. Any wording that
- required each successful
- \fIreaddir\fR()
- operation to mark the directory last data access timestamp
- for update would disallow such historical performance-oriented
- implementations.
- .P
- When returning a directory entry for the root of a mounted file system,
- some historical implementations of
- \fIreaddir\fR()
- returned the file serial number of the underlying mount point, rather
- than of the root of the mounted file system. This behavior is considered
- to be a bug, since the underlying file serial number has no significance
- to applications.
- .P
- Since
- \fIreaddir\fR()
- returns NULL
- when it detects an error and when the end of the directory is
- encountered, an application that needs to tell the difference must set
- .IR errno
- to zero before the call and check it if NULL is returned.
- Since the function must not change
- .IR errno
- in the second case and must set it to a non-zero value in the first
- case, a zero
- .IR errno
- after a call returning NULL indicates end-of-directory; otherwise, an
- error.
- .P
- Routines to deal with this problem more directly were proposed:
- .sp
- .RS 4
- .nf
- int derror (\fIdirp\fP)
- DIR *\fIdirp\fP;
- .P
- void clearderr (\fIdirp\fP)
- DIR *\fIdirp\fP;
- .fi
- .P
- .RE
- .P
- The first would indicate whether an error had occurred, and the second
- would clear the error indication. The simpler method involving
- .IR errno
- was adopted instead by requiring that
- \fIreaddir\fR()
- not change
- .IR errno
- when end-of-directory is encountered.
- .P
- An error or signal indicating that a directory has changed while open
- was considered but rejected.
- .P
- The thread-safe version of the directory reading function returns
- values in a user-supplied buffer instead of possibly using a static
- data area that may be overwritten by each call. Either the
- {NAME_MAX}
- compile-time constant or the corresponding
- \fIpathconf\fR()
- option can be used to determine the maximum sizes of returned
- pathnames.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIclosedir\fR\^(\|)",
- .IR "\fIdirfd\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIfdopendir\fR\^(\|)",
- .IR "\fIfstatat\fR\^(\|)",
- .IR "\fIrewinddir\fR\^(\|)",
- .IR "\fIsymlink\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<dirent.h>\fP",
- .IR "\fB<sys_types.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .