Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / directory.3
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. All advertising materials mentioning features or use of this software
13 .\"    must display the following acknowledgement:
14 .\"     This product includes software developed by the University of
15 .\"     California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     @(#)directory.3 8.1 (Berkeley) 6/4/93
33 .\" $FreeBSD: src/lib/libc/gen/directory.3,v 1.7.2.5 2003/03/15 15:11:05 trhodes Exp $
34 .\" $DragonFly: src/lib/libc/gen/directory.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
35 .\"
36 .Dd June 4, 1993
37 .Dt DIRECTORY 3
38 .Os
39 .Sh NAME
40 .Nm opendir ,
41 .Nm readdir ,
42 .Nm readdir_r ,
43 .Nm telldir ,
44 .Nm seekdir ,
45 .Nm rewinddir ,
46 .Nm closedir ,
47 .Nm dirfd
48 .Nd directory operations
49 .Sh LIBRARY
50 .Lb libc
51 .Sh SYNOPSIS
52 .In sys/types.h
53 .In dirent.h
54 .Ft DIR *
55 .Fn opendir "const char *filename"
56 .Ft struct dirent *
57 .Fn readdir "DIR *dirp"
58 .Ft int
59 .Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result"
60 .Ft long
61 .Fn telldir "DIR *dirp"
62 .Ft void
63 .Fn seekdir "DIR *dirp" "long  loc"
64 .Ft void
65 .Fn rewinddir "DIR *dirp"
66 .Ft int
67 .Fn closedir "DIR *dirp"
68 .Ft int
69 .Fn dirfd "DIR *dirp"
70 .Sh DESCRIPTION
71 The
72 .Fn opendir
73 function
74 opens the directory named by
75 .Fa filename ,
76 associates a
77 .Em directory stream
78 with it
79 and
80 returns a pointer to be used to identify the
81 .Em directory stream
82 in subsequent operations.  The pointer
83 .Dv NULL
84 is returned if
85 .Fa filename
86 cannot be accessed, or if it cannot
87 .Xr malloc 3
88 enough memory to hold the whole thing.
89 .Pp
90 The
91 .Fn readdir
92 function
93 returns a pointer to the next directory entry.  It returns
94 .Dv NULL
95 upon reaching the end of the directory or detecting an invalid
96 .Fn seekdir
97 operation.
98 .Pp
99 The
100 .Fn readdir_r
101 function
102 provides the same functionality as
103 .Fn readdir ,
104 but the caller must provide a directory
105 .Fa entry
106 buffer to store the results in.  If the read succeeds,
107 .Fa result
108 is pointed at the
109 .Fa entry ;
110 upon reaching the end of the directory
111 .Fa result
112 is set to
113 .Dv NULL .
114 The
115 .Fn readdir_r
116 function
117 returns 0 on success or an error number to indicate failure.
118 .Pp
119 The
120 .Fn telldir
121 function
122 returns the current location associated with the named
123 .Em directory stream .
124 Values returned by
125 .Fn telldir
126 are good only for the lifetime of the
127 .Dv DIR
128 pointer,
129 .Fa dirp ,
130 from which they are derived.  If the directory is closed and then
131 reopened, prior values returned by
132 .Fn telldir
133 will no longer be valid.
134 .Pp
135 The
136 .Fn seekdir
137 function
138 sets the position of the next
139 .Fn readdir
140 operation on the
141 .Em directory stream .
142 The new position reverts to the one associated with the
143 .Em directory stream
144 when the
145 .Fn telldir
146 operation was performed.
147 .Pp
148 The
149 .Fn rewinddir
150 function
151 resets the position of the named
152 .Em directory stream
153 to the beginning of the directory.
154 .Pp
155 The
156 .Fn closedir
157 function
158 closes the named
159 .Em directory stream
160 and frees the structure associated with the
161 .Fa dirp
162 pointer,
163 returning 0 on success.
164 On failure, \-1 is returned and the global variable
165 .Va errno
166 is set to indicate the error.
167 .Pp
168 The
169 .Fn dirfd
170 function
171 returns the integer file descriptor associated with the named
172 .Em directory stream ,
173 see
174 .Xr open 2 .
175 .Pp
176 Sample code which searches a directory for entry ``name'' is:
177 .Bd -literal -offset indent
178 len = strlen(name);
179 dirp = opendir(".");
180 while ((dp = readdir(dirp)) != NULL)
181         if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
182                 (void)closedir(dirp);
183                 return FOUND;
184         }
185 (void)closedir(dirp);
186 return NOT_FOUND;
187 .Ed
188 .Sh SEE ALSO
189 .Xr close 2 ,
190 .Xr lseek 2 ,
191 .Xr open 2 ,
192 .Xr read 2 ,
193 .Xr dir 5
194 .Sh HISTORY
195 The
196 .Fn opendir ,
197 .Fn readdir ,
198 .Fn telldir ,
199 .Fn seekdir ,
200 .Fn rewinddir ,
201 .Fn closedir ,
202 and
203 .Fn dirfd
204 functions appeared in
205 .Bx 4.2 .