diff options
Diffstat (limited to 'man3/readdir.3')
| -rw-r--r-- | man3/readdir.3 | 304 |
1 files changed, 0 insertions, 304 deletions
diff --git a/man3/readdir.3 b/man3/readdir.3 deleted file mode 100644 index 731e25c85..000000000 --- a/man3/readdir.3 +++ /dev/null @@ -1,304 +0,0 @@ -'\" 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) |