xref: /freebsd/lib/libc/gen/directory.3 (revision 02e9120893770924227138ba49df1edb3896112a)
1.\" Copyright (c) 1983, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd August 1, 2020
29.Dt DIRECTORY 3
30.Os
31.Sh NAME
32.Nm opendir ,
33.Nm fdopendir ,
34.Nm readdir ,
35.Nm readdir_r ,
36.Nm telldir ,
37.Nm seekdir ,
38.Nm rewinddir ,
39.Nm closedir ,
40.Nm fdclosedir ,
41.Nm dirfd
42.Nd directory operations
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In dirent.h
47.Ft DIR *
48.Fn opendir "const char *filename"
49.Ft DIR *
50.Fn fdopendir "int fd"
51.Ft struct dirent *
52.Fn readdir "DIR *dirp"
53.Ft int
54.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
55.Ft long
56.Fn telldir "DIR *dirp"
57.Ft void
58.Fn seekdir "DIR *dirp" "long loc"
59.Ft void
60.Fn rewinddir "DIR *dirp"
61.Ft int
62.Fn closedir "DIR *dirp"
63.Ft int
64.Fn fdclosedir "DIR *dirp"
65.Ft int
66.Fn dirfd "DIR *dirp"
67.Sh DESCRIPTION
68.Bf -symbolic
69The
70.Fn readdir_r
71interface is deprecated
72because it cannot be used correctly unless
73.Brq Va NAME_MAX
74is a fixed value.
75.Ef
76.Pp
77The
78.Fn opendir
79function
80opens the directory named by
81.Fa filename ,
82associates a
83.Em directory stream
84with it
85and
86returns a pointer to be used to identify the
87.Em directory stream
88in subsequent operations.
89The pointer
90.Dv NULL
91is returned if
92.Fa filename
93cannot be accessed, or if it cannot
94.Xr malloc 3
95enough memory to hold the whole thing.
96.Pp
97The
98.Fn fdopendir
99function is equivalent to the
100.Fn opendir
101function except that the directory is specified by a file descriptor
102.Fa fd
103rather than by a name.
104The file offset associated with the file descriptor at the time of the call
105determines which entries are returned.
106.Pp
107Upon successful return from
108.Fn fdopendir ,
109the file descriptor is under the control of the system,
110and if any attempt is made to close the file descriptor,
111or to modify the state of the associated description other than by means
112of
113.Fn closedir ,
114.Fn readdir ,
115.Fn readdir_r ,
116or
117.Fn rewinddir ,
118the behavior is undefined.
119Upon calling
120.Fn closedir
121the file descriptor is closed.
122The
123.Dv FD_CLOEXEC
124flag is set on the file descriptor by a successful call to
125.Fn fdopendir .
126.Pp
127The
128.Fn readdir
129function
130returns a pointer to the next directory entry.
131The directory entry remains valid until the next call to
132.Fn readdir
133or
134.Fn closedir
135on the same
136.Em directory stream .
137The function returns
138.Dv NULL
139upon reaching the end of the directory or on error.
140In the event of an error,
141.Va errno
142may be set to any of the values documented for the
143.Xr getdirentries 2
144system call.
145.Pp
146The
147.Fn readdir_r
148function
149provides the same functionality as
150.Fn readdir ,
151but the caller must provide a directory
152.Fa entry
153buffer to store the results in.
154The buffer must be large enough for a
155.Vt struct dirent
156with a
157.Va d_name
158array with
159.Brq Va NAME_MAX
160+ 1 elements.
161If the read succeeds,
162.Fa result
163is pointed at the
164.Fa entry ;
165upon reaching the end of the directory
166.Fa result
167is set to
168.Dv NULL .
169The
170.Fn readdir_r
171function
172returns 0 on success or an error number to indicate failure.
173.Pp
174The
175.Fn telldir
176function
177returns a token representing the current location associated with the named
178.Em directory stream .
179Values returned by
180.Fn telldir
181are good only for the lifetime of the
182.Dv DIR
183pointer,
184.Fa dirp ,
185from which they are derived.
186If the directory is closed and then
187reopened, prior values returned by
188.Fn telldir
189will no longer be valid.
190Values returned by
191.Fn telldir
192are also invalidated by a call to
193.Fn rewinddir .
194.Pp
195The
196.Fn seekdir
197function
198sets the position of the next
199.Fn readdir
200operation on the
201.Em directory stream .
202The new position reverts to the one associated with the
203.Em directory stream
204when the
205.Fn telldir
206operation was performed.
207.Pp
208The
209.Fn rewinddir
210function
211resets the position of the named
212.Em directory stream
213to the beginning of the directory.
214.Pp
215The
216.Fn closedir
217function
218closes the named
219.Em directory stream
220and frees the structure associated with the
221.Fa dirp
222pointer,
223returning 0 on success.
224On failure, \-1 is returned and the global variable
225.Va errno
226is set to indicate the error.
227.Pp
228The
229.Fn fdclosedir
230function is equivalent to the
231.Fn closedir
232function except that this function returns directory file descriptor instead of
233closing it.
234.Pp
235The
236.Fn dirfd
237function
238returns the integer file descriptor associated with the named
239.Em directory stream ,
240see
241.Xr open 2 .
242.Sh EXAMPLES
243Sample code which searches a directory for entry ``name'' is:
244.Bd -literal -offset indent
245dirp = opendir(".");
246if (dirp == NULL)
247	return (ERROR);
248len = strlen(name);
249while ((dp = readdir(dirp)) != NULL) {
250	if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
251		(void)closedir(dirp);
252		return (FOUND);
253	}
254}
255(void)closedir(dirp);
256return (NOT_FOUND);
257.Ed
258.Sh ERRORS
259The
260.Fn opendir
261function will fail if:
262.Bl -tag -width Er
263.It Bq Er EACCES
264Search permission is denied for the component of the path prefix of
265.Fa filename
266or read permission is denied for
267.Fa filename .
268.It Bq Er ELOOP
269A loop exists in symbolic links encountered during resolution of the
270.Fa filename
271argument.
272.It Bq Er ENAMETOOLONG
273The length of the
274.Fa filename
275argument exceeds
276.Brq Dv PATH_MAX
277or
278a pathname component is longer than
279.Brq Dv NAME_MAX .
280.It Bq Er ENOENT
281A component of
282.Fa filename
283does not name an existing directory or
284.Fa filename
285is an empty string.
286.It Bq Er ENOTDIR
287A component of
288.Fa filename
289is not a directory.
290.El
291.Pp
292The
293.Fn fdopendir
294function will fail if:
295.Bl -tag -width Er
296.It Bq Er EBADF
297The
298.Fa fd
299argument is not a valid file descriptor open for reading.
300.It Bq Er ENOTDIR
301The descriptor
302.Fa fd
303is not associated with a directory.
304.El
305.Pp
306The
307.Fn readdir
308and
309.Fn readdir_r
310functions may also fail and set
311.Va errno
312for any of the errors specified for the routine
313.Xr getdents 2 .
314.Pp
315The
316.Fn telldir
317function may also fail and set
318.Va errno
319for any of the errors specified for the routine
320.Xr realloc 3 .
321.Pp
322The
323.Fn closedir
324function may also fail and set
325.Va errno
326for any of the errors specified for the routine
327.Xr close 2 .
328.Sh SEE ALSO
329.Xr close 2 ,
330.Xr lseek 2 ,
331.Xr open 2 ,
332.Xr read 2 ,
333.Xr dir 5
334.Sh STANDARDS
335The
336.Fn closedir ,
337.Fn dirfd ,
338.Fn fdopendir ,
339.Fn opendir ,
340.Fn readdir ,
341.Fn readdir_r ,
342.Fn rewinddir ,
343.Fn seekdir
344and
345.Fn telldir
346functions are expected to conform to
347.St -p1003.1-2008 .
348The
349.Fn fdclosedir
350function and the
351.Fa d_off ,
352.Fa d_reclen
353and
354.Fa d_type
355fields of
356.Vt struct dirent
357are non-standard, and should not be used in portable programs.
358.Sh HISTORY
359The
360.Fn opendir ,
361.Fn readdir ,
362.Fn telldir ,
363.Fn seekdir ,
364.Fn rewinddir ,
365.Fn closedir ,
366and
367.Fn dirfd
368functions appeared in
369.Bx 4.2 .
370The
371.Fn fdopendir
372function appeared in
373.Fx 8.0 .
374.Fn fdclosedir
375function appeared in
376.Fx 10.0 .
377.Sh BUGS
378The behaviour of
379.Fn telldir
380and
381.Fn seekdir
382is likely to be wrong if there are parallel unlinks happening
383and the directory is larger than one page.
384There is code to ensure that a
385.Fn seekdir
386to the location given by a
387.Fn telldir
388immediately before the last
389.Fn readdir
390will always set the correct location to return the same value as that last
391.Fn readdir
392performed.
393This is enough for some applications which want to
394"push back the last entry read", e.g., Samba.
395Seeks back to any other location,
396other than the beginning of the directory,
397may result in unexpected behaviour if deletes are present.
398It is hoped that this situation will be resolved with changes to
399.Fn getdirentries
400and the VFS.
401