| .\" 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 2019-03-06 "" "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 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\e0\(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) |