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.\" 4. 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.\" @(#)directory.3 8.1 (Berkeley) 6/4/93
|
30.\"
31.Dd July 28, 2014
32.Dt DIRECTORY 3
33.Os
34.Sh NAME
35.Nm opendir ,
36.Nm fdopendir ,
37.Nm readdir ,
38.Nm readdir_r ,
39.Nm telldir ,
40.Nm seekdir ,
41.Nm rewinddir ,
42.Nm closedir ,
43.Nm fdclosedir ,
44.Nm dirfd
45.Nd directory operations
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In sys/types.h
50.In dirent.h
51.Ft DIR *
52.Fn opendir "const char *filename"
53.Ft DIR *
54.Fn fdopendir "int fd"
55.Ft struct dirent *
56.Fn readdir "DIR *dirp"
57.Ft int
58.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
59.Ft long
60.Fn telldir "DIR *dirp"
61.Ft void
62.Fn seekdir "DIR *dirp" "long loc"
63.Ft void
64.Fn rewinddir "DIR *dirp"
65.Ft int
66.Fn closedir "DIR *dirp"
67.Ft int
68.Fn fdclosedir "DIR *dirp"
69.Ft int
70.Fn dirfd "DIR *dirp"
71.Sh DESCRIPTION
72The
73.Fn opendir
74function
75opens the directory named by
76.Fa filename ,
77associates a
78.Em directory stream
79with it
80and
81returns a pointer to be used to identify the
82.Em directory stream
83in subsequent operations.
84The pointer
85.Dv NULL
86is returned if
87.Fa filename
88cannot be accessed, or if it cannot
89.Xr malloc 3
90enough memory to hold the whole thing.
91.Pp
92The
93.Fn fdopendir
94function is equivalent to the
95.Fn opendir
96function except that the directory is specified by a file descriptor
97.Fa fd
98rather than by a name.
99The file offset associated with the file descriptor at the time of the call
100determines which entries are returned.
101.Pp
102Upon successful return from
103.Fn fdopendir ,
104the file descriptor is under the control of the system,
105and if any attempt is made to close the file descriptor,
106or to modify the state of the associated description other than by means
107of
108.Fn closedir ,
109.Fn readdir ,
110.Fn readdir_r ,
111or
112.Fn rewinddir ,
113the behavior is undefined.
114Upon calling
115.Fn closedir
116the file descriptor is closed.
117The
118.Dv FD_CLOEXEC
119flag is set on the file descriptor by a successful call to
120.Fn fdopendir .
121.Pp
122The
123.Fn readdir
124function
125returns a pointer to the next directory entry.
126It returns
127.Dv NULL
128upon reaching the end of the directory or on error.
129In the event of an error,
130.Va errno
131may be set to any of the values documented for the
132.Xr getdirentries 2
133system call.
134.Pp
135The
136.Fn readdir_r
137function
138provides the same functionality as
139.Fn readdir ,
140but the caller must provide a directory
141.Fa entry
142buffer to store the results in.
143If the read succeeds,
144.Fa result
145is pointed at the
146.Fa entry ;
147upon reaching the end of the directory
148.Fa result
149is set to
150.Dv NULL .
151The
152.Fn readdir_r
153function
154returns 0 on success or an error number to indicate failure.
155.Pp
156The
157.Fn telldir
158function
159returns a token representing the current location associated with the named
160.Em directory stream .
161Values returned by
162.Fn telldir
163are good only for the lifetime of the
164.Dv DIR
165pointer,
166.Fa dirp ,
167from which they are derived.
168If the directory is closed and then
169reopened, prior values returned by
170.Fn telldir
171will no longer be valid.
172Values returned by
173.Fn telldir
174are also invalidated by a call to
175.Fn rewinddir .
176.Pp
177The
178.Fn seekdir
179function
180sets the position of the next
181.Fn readdir
182operation on the
183.Em directory stream .
184The new position reverts to the one associated with the
185.Em directory stream
186when the
187.Fn telldir
188operation was performed.
189.Pp
190The
191.Fn rewinddir
192function
193resets the position of the named
194.Em directory stream
195to the beginning of the directory.
196.Pp
197The
198.Fn closedir
199function
200closes the named
201.Em directory stream
202and frees the structure associated with the
203.Fa dirp
204pointer,
205returning 0 on success.
206On failure, \-1 is returned and the global variable
207.Va errno
208is set to indicate the error.
209.Pp
210The
211.Fn fdclosedir
212function is equivalent to the
213.Fn closedir
214function except that this function returns directory file descriptor instead of
215closing it.
216.Pp
217The
218.Fn dirfd
219function
220returns the integer file descriptor associated with the named
221.Em directory stream ,
222see
223.Xr open 2 .
224.Pp
225Sample code which searches a directory for entry ``name'' is:
226.Bd -literal -offset indent
227dirp = opendir(".");
228if (dirp == NULL)
229 return (ERROR);
230len = strlen(name);
231while ((dp = readdir(dirp)) != NULL) {
232 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) {
233 (void)closedir(dirp);
234 return (FOUND);
235 }
236}
237(void)closedir(dirp);
238return (NOT_FOUND);
239.Ed
240.Sh SEE ALSO
241.Xr close 2 ,
242.Xr lseek 2 ,
243.Xr open 2 ,
244.Xr read 2 ,
245.Xr dir 5
246.Sh HISTORY
247The
248.Fn opendir ,
249.Fn readdir ,
250.Fn telldir ,
251.Fn seekdir ,
252.Fn rewinddir ,
253.Fn closedir ,
254and
255.Fn dirfd
256functions appeared in
257.Bx 4.2 .
258The
259.Fn fdopendir
260function appeared in
261.Fx 8.0 .
262.Fn fdclosedir
263function appeared in
264.Fx 10.0 .
265.Sh BUGS
266The invalidation of
267.Fn telldir
268tokens when calling
269.Fn seekdir
|