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