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