mirror of https://github.com/mkerrisk/man-pages
314 lines
8.3 KiB
Groff
314 lines
8.3 KiB
Groff
.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\" and Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2016-03-15 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
readdir \- read a directory
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <dirent.h>
|
|
.PP
|
|
.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.
|
|
.PP
|
|
In the glibc implementation, the
|
|
.I dirent
|
|
structure is defined as follows:
|
|
.PP
|
|
.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
|
|
.PP
|
|
The only fields in the
|
|
.I dirent
|
|
structure that are mandated by POSIX.1 are
|
|
.IR d_name
|
|
and
|
|
.IR d_ino .
|
|
The other fields are unstandardized, and not present on all systems;
|
|
see NOTES below for some further details.
|
|
.PP
|
|
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
|
|
on glibc versions since 2.19, or
|
|
.BR _BSD_SOURCE
|
|
on glibc versions 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" .
|
|
.PP
|
|
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.)
|
|
.PP
|
|
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 appropriately.
|
|
To distinguish end of stream and 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;
|
|
lb lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR readdir ()
|
|
T} Thread safety MT-Unsafe race:dirstream
|
|
.TE
|
|
.sp 1
|
|
.PP
|
|
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 CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
|
|
.SH NOTES
|
|
A directory stream is opened using
|
|
.BR opendir (3).
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
.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\\0\(aq).
|
|
.PP
|
|
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
|
|
.IR strlen(d_name)
|
|
instead.
|
|
(On some systems, this field is defined as
|
|
.IR char\ d_name[1] !)
|
|
By implication, the use
|
|
.IR "sizeof(struct dirent)"
|
|
to capture the size of the record including the size of
|
|
.IR d_name
|
|
is also incorrect.
|
|
.PP
|
|
Note that while the call
|
|
.PP
|
|
fpathconf(fd, _PC_NAME_MAX)
|
|
.PP
|
|
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 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)
|