diff options
Diffstat (limited to 'upstream/archlinux/man3p/readdir.3p')
| -rw-r--r-- | upstream/archlinux/man3p/readdir.3p | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/readdir.3p b/upstream/archlinux/man3p/readdir.3p new file mode 100644 index 00000000..98f5f3d7 --- /dev/null +++ b/upstream/archlinux/man3p/readdir.3p @@ -0,0 +1,377 @@ +'\" 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 . |