xref: /dragonfly/lib/libc/gen/directory.3 (revision cfd1aba3) 
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.\"     @(#)directory.3	8.1 (Berkeley) 6/4/93
29.\" $FreeBSD: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $
30.\" $DragonFly: src/lib/libc/gen/directory.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
31.\"
32.Dd August 2, 2009
33.Dt DIRECTORY 3
34.Os
35.Sh NAME
36.Nm fdopendir ,
37.Nm opendir ,
38.Nm readdir ,
39.Nm readdir_r ,
40.Nm telldir ,
41.Nm seekdir ,
42.Nm rewinddir ,
43.Nm closedir ,
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 fdopendir "int fd"
53.Ft DIR *
54.Fn opendir "const char *filename"
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 dirfd "DIR *dirp"
69.Sh DESCRIPTION
70The
71.Fn opendir
72function
73opens the directory named by
74.Fa filename ,
75associates a
76.Em directory stream
77with it
78and
79returns a pointer to be used to identify the
80.Em directory stream
81in subsequent operations.  The 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 associates a
92.Em directory stream
93with the directory file descriptor
94.Fa fd .
95The file offset associated with
96.Fa fd
97at the time of the call determines which entries are returned.
98The file descriptor must not be used further by the caller in any way.
99.Pp
100The
101.Fn readdir
102function
103returns a pointer to the next directory entry.  It returns
104.Dv NULL
105upon reaching the end of the directory or detecting an invalid
106.Fn seekdir
107operation.
108.Pp
109The
110.Fn readdir_r
111function
112provides the same functionality as
113.Fn readdir ,
114but the caller must provide a directory
115.Fa entry
116buffer to store the results in.  If the read succeeds,
117.Fa result
118is pointed at the
119.Fa entry ;
120upon reaching the end of the directory
121.Fa result
122is set to
123.Dv NULL .
124The
125.Fn readdir_r
126function
127returns 0 on success or an error number to indicate failure.
128.Pp
129The
130.Fn telldir
131function
132returns the current location associated with the named
133.Em directory stream .
134Values returned by
135.Fn telldir
136are good only for the lifetime of the
137.Dv DIR
138pointer,
139.Fa dirp ,
140from which they are derived.  If the directory is closed and then
141reopened, prior values returned by
142.Fn telldir
143will no longer be valid.
144.Pp
145The
146.Fn seekdir
147function
148sets the position of the next
149.Fn readdir
150operation on the
151.Em directory stream .
152The new position reverts to the one associated with the
153.Em directory stream
154when the
155.Fn telldir
156operation was performed.
157.Pp
158The
159.Fn rewinddir
160function
161resets the position of the named
162.Em directory stream
163to the beginning of the directory.
164.Pp
165The
166.Fn closedir
167function
168closes the named
169.Em directory stream
170and frees the structure associated with the
171.Fa dirp
172pointer,
173returning 0 on success.
174On failure, \-1 is returned and the global variable
175.Va errno
176is set to indicate the error.
177.Pp
178The
179.Fn dirfd
180function
181returns the integer file descriptor associated with the named
182.Em directory stream ,
183see
184.Xr open 2 .
185.Pp
186Sample code which searches a directory for entry ``name'' is:
187.Bd -literal -offset indent
188len = strlen(name);
189dirp = opendir(".");
190while ((dp = readdir(dirp)) != NULL)
191	if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
192		(void)closedir(dirp);
193		return FOUND;
194	}
195(void)closedir(dirp);
196return NOT_FOUND;
197.Ed
198.Sh SEE ALSO
199.Xr close 2 ,
200.Xr lseek 2 ,
201.Xr open 2 ,
202.Xr read 2 ,
203.Xr dir 5
204.Sh HISTORY
205The
206.Fn opendir ,
207.Fn readdir ,
208.Fn telldir ,
209.Fn seekdir ,
210.Fn rewinddir ,
211.Fn closedir ,
212and
213.Fn dirfd
214functions appeared in
215.Bx 4.2 .
216