summaryrefslogtreecommitdiffstats
path: root/man3/readdir.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/readdir.3')
-rw-r--r--man3/readdir.3304
1 files changed, 0 insertions, 304 deletions
diff --git a/man3/readdir.3 b/man3/readdir.3
deleted file mode 100644
index 9b61aaf..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)