diff options
Diffstat (limited to 'man/man3/readdir.3')
| -rw-r--r-- | man/man3/readdir.3 | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/man/man3/readdir.3 b/man/man3/readdir.3 new file mode 100644 index 000000000..731e25c85 --- /dev/null +++ b/man/man3/readdir.3 @@ -0,0 +1,304 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>, mtk: +.\" Rework discussion of nonstandard structure fields. +.\" +.TH readdir 3 (date) "Linux man-pages (unreleased)" +.SH NAME +readdir \- read a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <dirent.h> +.P +.BI "struct dirent *readdir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR readdir () +function returns a pointer to a \fIdirent\fP structure +representing the next directory entry in the directory stream pointed +to by \fIdirp\fP. +It returns NULL on reaching the end of the directory stream or if +an error occurred. +.P +In the glibc implementation, the +.I dirent +structure is defined as follows: +.P +.in +4n +.EX +struct dirent { + ino_t d_ino; /* Inode number */ + off_t d_off; /* Not an offset; see below */ + unsigned short d_reclen; /* Length of this record */ + unsigned char d_type; /* Type of file; not supported + by all filesystem types */ + char d_name[256]; /* Null\-terminated filename */ +}; +.EE +.in +.P +The only fields in the +.I dirent +structure that are mandated by POSIX.1 are +.I d_name +and +.IR d_ino . +The other fields are unstandardized, and not present on all systems; +see NOTES below for some further details. +.P +The fields of the +.I dirent +structure are as follows: +.TP +.I d_ino +This is the inode number of the file. +.TP +.I d_off +The value returned in +.I d_off +is the same as would be returned by calling +.BR telldir (3) +at the current position in the directory stream. +Be aware that despite its type and name, the +.I d_off +field is seldom any kind of directory offset on modern filesystems. +.\" https://lwn.net/Articles/544298/ +Applications should treat this field as an opaque value, +making no assumptions about its contents; see also +.BR telldir (3). +.TP +.I d_reclen +This is the size (in bytes) of the returned record. +This may not match the size of the structure definition shown above; +see NOTES. +.TP +.I d_type +This field contains a value indicating the file type, +making it possible to avoid the expense of calling +.BR lstat (2) +if further actions depend on the type of the file. +.IP +When a suitable feature test macro is defined +.RB ( _DEFAULT_SOURCE +since glibc 2.19, or +.B _BSD_SOURCE +on glibc 2.19 and earlier), +glibc defines the following macro constants for the value returned in +.IR d_type : +.RS +.TP 12 +.B DT_BLK +This is a block device. +.TP +.B DT_CHR +This is a character device. +.TP +.B DT_DIR +This is a directory. +.TP +.B DT_FIFO +This is a named pipe (FIFO). +.TP +.B DT_LNK +This is a symbolic link. +.TP +.B DT_REG +This is a regular file. +.TP +.B DT_SOCK +This is a UNIX domain socket. +.TP +.B DT_UNKNOWN +The file type could not be determined. +.RE +.IP +Currently, +.\" kernel 2.6.27 +.\" The same sentence is in getdents.2 +only some filesystems (among them: Btrfs, ext2, ext3, and ext4) +have full support for returning the file type in +.IR d_type . +All applications must properly handle a return of +.BR DT_UNKNOWN . +.TP +.I d_name +This field contains the null terminated filename. +.IR "See NOTES" . +.P +The data returned by +.BR readdir () +may be overwritten by subsequent calls to +.BR readdir () +for the same directory stream. +.SH RETURN VALUE +On success, +.BR readdir () +returns a pointer to a +.I dirent +structure. +(This structure may be statically allocated; do not attempt to +.BR free (3) +it.) +.P +If the end of the directory stream is reached, NULL is returned and +.I errno +is not changed. +If an error occurs, NULL is returned and +.I errno +is set to indicate the error. +To distinguish end of stream from an error, set +.I errno +to zero before calling +.BR readdir () +and then check the value of +.I errno +if NULL is returned. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR readdir () +T} Thread safety MT-Unsafe race:dirstream +.TE +.P +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir () +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir () +that specify different directory streams are thread-safe. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir () +with external synchronization is still preferable to the use of the deprecated +.BR readdir_r (3) +function. +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will require that +.BR readdir () +be thread-safe when concurrently employed on different directory streams. +.SH VERSIONS +Only the fields +.I d_name +and (as an XSI extension) +.I d_ino +are specified in POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +Other than Linux, the +.I d_type +field is available mainly only on BSD systems. +The remaining fields are available on many, but not all systems. +Under glibc, +programs can check for the availability of the fields not defined +in POSIX.1 by testing whether the macros +.BR _DIRENT_HAVE_D_NAMLEN , +.BR _DIRENT_HAVE_D_RECLEN , +.BR _DIRENT_HAVE_D_OFF , +or +.B _DIRENT_HAVE_D_TYPE +are defined. +.\" +.SS The d_name field +The +.I dirent +structure definition shown above is taken from the glibc headers, +and shows the +.I d_name +field with a fixed size. +.P +.IR Warning : +applications should avoid any dependence on the size of the +.I d_name +field. +POSIX defines it as +.IR "char\ d_name[]", +a character array of unspecified size, with at most +.B NAME_MAX +characters preceding the terminating null byte (\[aq]\e0\[aq]). +.P +POSIX.1 explicitly notes that this field should not be used as an lvalue. +The standard also notes that the use of +.I sizeof(d_name) +is incorrect; use +.I strlen(d_name) +instead. +(On some systems, this field is defined as +.IR char\~d_name[1] !) +By implication, the use +.I sizeof(struct dirent) +to capture the size of the record including the size of +.I d_name +is also incorrect. +.P +Note that while the call +.P +.in +4n +.EX +fpathconf(fd, _PC_NAME_MAX) +.EE +.in +.P +returns the value 255 for most filesystems, +on some filesystems (e.g., CIFS, Windows SMB servers), +the null-terminated filename that is (correctly) returned in +.I d_name +can actually exceed this size. +In such cases, the +.I d_reclen +field will contain a value that exceeds the size of the glibc +.I dirent +structure shown above. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +A directory stream is opened using +.BR opendir (3). +.P +The order in which filenames are read by successive calls to +.BR readdir () +depends on the filesystem implementation; +it is unlikely that the names will be sorted in any fashion. +.SH SEE ALSO +.BR getdents (2), +.BR read (2), +.BR closedir (3), +.BR dirfd (3), +.BR ftw (3), +.BR offsetof (3), +.BR opendir (3), +.BR readdir_r (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) |