xref: /illumos-gate/usr/src/man/man3c/readdir.3c (revision bbf21555)
1.\"
2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3.\" permission to reproduce portions of its copyrighted documentation.
4.\" Original documentation from The Open Group can be obtained online at
5.\" http://www.opengroup.org/bookstore/.
6.\"
7.\" The Institute of Electrical and Electronics Engineers and The Open
8.\" Group, have given us permission to reprint portions of their
9.\" documentation.
10.\"
11.\" In the following statement, the phrase ``this text'' refers to portions
12.\" of the system documentation.
13.\"
14.\" Portions of this text are reprinted and reproduced in electronic form
15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16.\" Standard for Information Technology -- Portable Operating System
17.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
20.\" between these versions and the original IEEE and The Open Group
21.\" Standard, the original IEEE and The Open Group Standard is the referee
22.\" document.  The original Standard can be obtained online at
23.\" http://www.opengroup.org/unix/online.html.
24.\"
25.\" This notice shall appear on any product containing this material.
26.\"
27.\" The contents of this file are subject to the terms of the
28.\" Common Development and Distribution License (the "License").
29.\" You may not use this file except in compliance with the License.
30.\"
31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32.\" or http://www.opensolaris.org/os/licensing.
33.\" See the License for the specific language governing permissions
34.\" and limitations under the License.
35.\"
36.\" When distributing Covered Code, include this CDDL HEADER in each
37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38.\" If applicable, add the following below this CDDL HEADER, with the
39.\" fields enclosed by brackets "[]" replaced with your own identifying
40.\" information: Portions Copyright [yyyy] [name of copyright owner]
41.\"
42.\"
43.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
44.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
45.\" Copyright 2021 Oxide Computer Company
46.\"
47.Dd February 25, 2021
48.Dt READDIR 3C
49.Os
50.Sh NAME
51.Nm readdir ,
52.Nm readdir_r
53.Nd read directory
54.Sh SYNOPSIS
55.In sys/types.h
56.In dirent.h
57.Ft "struct dirent *"
58.Fo readdir
59.Fa "DIR *dirp"
60.Fc
61.Ft "struct dirent *"
62.Fo readdir_r
63.Fa "DIR *dirp"
64.Fa "struct dirent *entry"
65.Fc
66.Ss Standard Conforming
67.Fd #define _POSIX_PTHREAD_SEMANTICS
68.Ft int
69.Fo readdir_r
70.Fa "DIR *restrict dirp"
71.Fa "struct dirent *restrict entry"
72.Fa "struct dirent **restrict result"
73.Fc
74.Sh DESCRIPTION
75The type
76.Ft DIR ,
77which is defined in the header
78.In dirent.h ,
79represents a
80.Em directory stream ,
81which is an ordered sequence of all the directory entries in a particular
82directory.
83Directory entries represent files.
84Files can be removed from a directory or added to a directory asynchronously
85to the operation of
86.Fn readdir
87and
88.Fn readdir_r .
89.Ss Fn readdir
90The
91.Fn readdir
92function returns a pointer to a structure representing the directory entry at
93the current position in the directory stream specified by the argument
94.Fa dirp ,
95and positions the directory stream at the next entry.
96It returns a null pointer upon reaching the end of the directory stream.
97The structure
98.Ft dirent
99defined by the
100.In dirent.h
101header describes a directory entry.
102.Pp
103The
104.Fn readdir
105function will not return directory entries containing empty names.
106If entries for
107.No \&.
108.Pq dot
109.No \&..
110.Pq dot-dot
111exist, one entry will be returned for dot and one entry will be returned for
112dot-dot; otherwise they will not be returned.
113.Pp
114The pointer returned by
115.Fn readdir
116points to data that can be overwritten by another call to
117.Fn readdir
118on the same directory stream.
119It will not be overwritten by another call to
120.Fn readdir
121on a different directory stream.
122The returned pointer will remain valid until the directory stream is
123freed with a call to
124.Xr closedir 3C .
125It is safe to use
126.Fn readdir
127in a threaded application, so long as only one thread reads from the directory
128stream at any given time.
129.Pp
130If a file is removed from or added to the directory after the most recent call
131to
132.Xr opendir 3C
133or
134.Xr rewinddir 3C ,
135whether a subsequent call to
136.Fn readdir
137returns an entry for that file is unspecified.
138.Pp
139The
140.Fn readdir
141function can buffer several directory entries per actual read operation.
142It marks for update the
143.Ft st_atime
144field of the directory each time the directory is actually read.
145.Pp
146After a call to
147.Xr fork 2 ,
148either the parent or child
149.Pq but not both
150can continue processing the directory stream using
151.Fn readdir ,
152.Xr rewinddir 3C ,
153or
154.Xr seekdir 3C .
155If both the parent and child processes use these functions, the result is
156undefined.
157.Pp
158If the entry names a symbolic link, the value of the
159.Ft d_ino
160member is unspecified.
161.Ss Fn readdir_r
162Unless the end of the directory stream has been reached or an error occurred,
163the
164.Fn readdir_r
165function initializes the
166.Ft dirent
167structure referenced by
168.Fa entry
169to represent the directory entry at the current position in the directory
170stream referred to by
171.Fa dirp ,
172and positions the directory stream at the next entry.
173.Pp
174The caller must allocate storage pointed to by
175.Fa entry
176to be large enough for a
177.Ft dirent
178structure with an array of
179.Ft char
180.Fa d_name
181member containing at least
182.Dv NAME_MAX
183.Po
184that is,
185.Fo pathconf
186.Fa directory ,
187.Dv _PC_NAME_MAX
188.Fc
189plus one element.
190.Po
191.Dv _PC_NAME_MAX
192is defined in
193.In unistd.h
194.Pc
195.Pc
196.Pp
197While the
198.Fn readdir_r function was originally added as a re-entrant version of
199.Fn readdir ,
200it is not recommended that
201.Fn readdir_r
202be used in new applications and existing software should instead use
203.Fn readdir .
204The
205.Fn readdir_r
206function has been deprecated in many systems.
207Historically, the data returned from
208.Fn readdir
209was not specific to the directory stream making it unsafe in a multi-threaded
210environment; however, that is no longer the case.
211.Pp
212The
213.Fn readdir_r
214function will not return directory entries containing empty names.
215It is unspecified whether entries are returned for
216.No \&.
217.Pq dot
218or
219.No \&..
220.Pq dot-dot .
221.Pp
222If a file is removed from or added to the directory after the most recent call
223to
224.Xr opendir 3C or
225.Xr rewinddir 3C , whether a subsequent call to
226.Fn readdir_r
227returns an entry for that file is unspecified.
228.Pp
229The
230.Fn readdir_r
231function can buffer several directory entries per actual read operation.
232It marks for update the
233.Ft st_atime
234field of the directory each time the directory is actually read.
235.Pp
236The standard-conforming version
237.Po see
238.Xr standards 7
239.Pc
240of the
241.Fn readdir_r
242function performs all of the actions described above for
243.Fn readdir_r
244and sets the pointer pointed to by
245.Fa result .
246If a directory entry is returned, the pointer will be set to the same value
247as the
248.Fa entry
249argument; otherwise, it will be set to
250.Dv NULL .
251.Sh RETURN VALUES
252Upon successful completion,
253.Fn readdir
254and the default
255.Fn readdir_r
256return a pointer to an object of type
257.Ft struct dirent .
258When an error is encountered, a null pointer is returned and
259.Va errno
260is set to indicate the error.
261When the end of the directory is encountered, a null pointer is returned and
262.Va errno
263is not changed.
264.Pp
265The standard-conforming
266.Fn readdir_r
267returns
268.Sy 0
269if the end of the directory is encountered or a directory entry is stored in
270the structure referenced by
271.Fa entry .
272Otherwise, an error number is returned to indicate the failure.
273.Sh EXAMPLES
274.Sy Example 1
275Search the current directory for the entry
276.Fa name .
277.Pp
278The following sample program will search the current directory for each of the
279arguments supplied on the command line:
280.Bd -literal
281#include <sys/types.h>
282#include <dirent.h>
283#include <errno.h>
284#include <stdio.h>
285#include <strings.h>
286
287static void
288lookup(const char *arg)
289{
290        DIR *dirp;
291        struct dirent *dp;
292
293        if ((dirp = opendir(".")) == NULL) {
294                perror("couldn't open '.'");
295                return;
296        }
297
298        do {
299                errno = 0;
300                if ((dp = readdir(dirp)) != NULL) {
301                        if (strcmp(dp->d_name, arg) != 0)
302                                continue;
303
304                        (void) printf("found %s\en", arg);
305                        (void) closedir(dirp);
306                        return;
307                }
308        } while (dp != NULL);
309
310        if (errno != 0)
311                perror("error reading directory");
312        else
313                (void) printf("failed to find %s\en", arg);
314        (void) closedir(dirp);
315}
316
317int
318main(int argc, char *argv[])
319{
320        int i;
321        for (i = 1; i < argc; i++)
322                lookup(argv[i]);
323        return (0);
324}
325.Ed
326.Sh ERRORS
327The
328.Fn readdir
329and
330.Fn readdir_r
331functions will fail if:
332.Bl -tag -width Er
333.It Er EOVERFLOW
334One of the values in the structure to be returned cannot be represented
335correctly.
336.El
337.Pp
338The
339.Fn readdir
340and
341.Fn readdir_r
342functions may fail if:
343.Bl -tag -width Er
344.It Er EBADF
345The
346.Fa dirp
347argument does not refer to an open directory stream.
348.It Er ENOENT
349The current position of the directory stream is invalid.
350.El
351.Sh USAGE
352The
353.Fn readdir
354and
355.Fn readdir_r
356functions should be used in conjunction with
357.Xr opendir 3C ,
358.Xr closedir 3C ,
359and
360.Xr rewinddir 3C
361to examine the contents of the directory.
362Since
363.Fn readdir
364and the default
365.Fn readdir_r
366return a null pointer both at the end of the directory and on error, an
367application wanting to check for error situations should set
368.Va errno
369to 0 before calling either of these functions.
370If
371.Va errno
372is set to non-zero on return, an error occurred.
373.Pp
374The standard-conforming
375.Fn readdir_r
376returns the error number if an error occurred.
377It returns 0 on success
378.Pq including reaching the end of the directory stream .
379.Pp
380The
381.Fn readdir
382and
383.Fn readdir_r
384functions have transitional interfaces for 64-bit file offsets.
385See
386.Xr lf64 7 .
387.Sh INTERFACE STABILITY
388.Sy Committed
389.Sh MT-LEVEL
390The
391.Fn readdir
392function is
393.Sy Unsafe ;
394however, it is
395.Sy Safe
396if different directory streams are used concurrently.
397The
398.Fn readdir_r
399function is
400.Sy Safe .
401.Sh SEE ALSO
402.Xr fork 2 ,
403.Xr lstat 2 ,
404.Xr symlink 2 ,
405.Xr Intro 3 ,
406.Xr closedir 3C ,
407.Xr opendir 3C ,
408.Xr rewinddir 3C ,
409.Xr scandir 3C ,
410.Xr seekdir 3C ,
411.Xr attributes 7 ,
412.Xr lf64 7 ,
413.Xr standards 7
414.Sh NOTES
415When compiling multithreaded programs, see the
416.Sy MULTITHREADED APPLICATIONS
417section of
418.Xr Intro 3 .
419.Pp
420Solaris 2.4 and earlier releases provided a
421.Fn readdir_r
422interface as specified in POSIX.1c Draft 6.
423The final POSIX.1c standard changed the interface as described above.
424Support for the Draft 6 interface is provided for compatibility only.
425New applications and libraries should use the standard-conforming interface,
426though preferably
427.Fn readdir .
428.Pp
429For POSIX.1c-conforming applications, the
430.Dv _POSIX_PTHREAD_SEMANTICS
431and
432.Dv _REENTRANT
433flags are automatically turned on by defining the
434.Dv _POSIX_C_SOURCE
435flag with a value >= 199506L.
436