1.\"	$OpenBSD: getdirentries.2,v 1.19 2005/06/18 18:09:42 millert Exp $
2.\"	$NetBSD: getdirentries.2,v 1.7 1995/10/12 15:40:50 jtc Exp $
3.\"
4.\" Copyright (c) 1989, 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"	@(#)getdirentries.2	8.1 (Berkeley) 6/9/93
32.\"
33.Dd June 9, 1993
34.Dt GETDIRENTRIES 2
35.Os
36.Sh NAME
37.Nm getdirentries
38.Nd "get directory entries in a filesystem independent format"
39.Sh SYNOPSIS
40.Fd #include <dirent.h>
41.Ft int
42.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
43.Sh DESCRIPTION
44.Fn getdirentries
45reads directory entries from the directory
46referenced by the file descriptor
47.Fa fd
48into the buffer pointed to by
49.Fa buf ,
50in a filesystem independent format.
51Up to
52.Fa nbytes
53of data will be transferred.
54.Fa nbytes
55must be greater than or equal to the
56block size associated with the file (see
57.Xr stat 2 ) .
58Some filesystems may not support
59.Fn getdirentries
60with buffers smaller than this size.
61.Pp
62The data in the buffer is a series of
63.Em dirent
64structures each containing the following entries:
65.Bd -literal -offset indent
66u_int32_t	d_fileno;
67u_int16_t	d_reclen;
68u_int8_t	d_type;
69u_int8_t	d_namlen;
70char    	d_name[MAXNAMLEN + 1]; /* see below */
71.Ed
72.Pp
73The
74.Fa d_fileno
75entry is a number which is unique for each distinct file in the filesystem.
76Files that are linked by hard links (see
77.Xr link 2 )
78have the same
79.Fa d_fileno .
80The
81.Fa d_reclen
82entry is the length, in bytes, of the directory record.
83.Pp
84The
85.Fa d_type
86is the type of file, where the following are possible types:
87.Dv DT_UNKNOWN ,
88.Dv DT_FIFO ,
89.Dv DT_CHR ,
90.Dv DT_DIR ,
91.Dv DT_BLK ,
92.Dv DT_REG ,
93.Dv DT_LNK ,
94and
95.Dv DT_SOCK .
96.Pp
97The
98.Fa d_namlen
99entry specifies the length of the file name excluding the NUL byte.
100Thus the actual size of
101.Fa d_name
102may vary from 1 to
103.Dv MAXNAMLEN
104\&+ 1.
105.Pp
106The
107.Fa d_name
108entry contains a NUL-terminated file name.
109.Pp
110Entries may be separated by extra space.
111The
112.Fa d_reclen
113entry may be used as an offset from the start of a
114.Fa dirent
115structure to the next structure, if any.
116.Pp
117Invalid entries with
118.Fa d_fileno
119set to 0 may be returned among regular entries.
120.Pp
121The actual number of bytes transferred is returned.
122The current position pointer associated with
123.Fa fd
124is set to point to the next block of entries.
125The pointer may not advance by the number of bytes returned by
126.Fn getdirentries .
127.Pp
128.Fn getdirentries
129writes the position of the block read into the location pointed to by
130.Fa basep .
131Alternatively, the current position pointer may be set and retrieved by
132.Xr lseek 2 .
133The current position pointer should only be set to a value returned by
134.Xr lseek 2 ,
135a value returned in the location pointed to by
136.Fa basep ,
137or zero.
138.Sh RETURN VALUES
139If successful, the number of bytes actually transferred is returned.
140A value of zero is returned when
141the end of the directory has been reached.
142Otherwise, \-1 is returned and the global variable
143.Va errno
144is set to indicate the error.
145.Sh EXAMPLES
146The following code may be used to iterate on all entries in a
147directory:
148.Bd -literal -offset indent
149char *buf, *ebuf, *cp;
150long base;
151size_t bufsize;
152int fd, nbytes;
153char *path;
154struct stat sb;
155struct dirent *dp;
156
157if ((fd = open(path, O_RDONLY)) < 0)
158	err(2, "cannot open %s", path);
159if (fstat(fd, &sb) < 0)
160	err(2, "fstat");
161bufsize = sb.st_size;
162if (bufsize < sb.st_blksize)
163	bufsize = sb.st_blksize;
164if ((buf = malloc(bufsize)) == NULL)
165	err(2,  "cannot malloc %lu bytes", (unsigned long)bufsize);
166while ((nbytes = getdirentries(fd, buf, bufsize, &base)) > 0) {
167	ebuf = buf + nbytes;
168	cp = buf;
169	while (cp < ebuf) {
170		dp = (struct dirent *)cp;
171		printf("%s\en", dp->d_name);
172		cp += dp->d_reclen;
173	}
174}
175if (nbytes < 0)
176	err(2, "getdirentries");
177free(buf);
178.Ed
179.Sh ERRORS
180.Fn getdirentries
181will fail if:
182.Bl -tag -width Er
183.It Bq Er EBADF
184.Fa fd
185is not a valid file descriptor open for reading.
186.It Bq Er EFAULT
187Either
188.Fa buf
189or
190.Fa basep
191points outside the allocated address space.
192.It Bq Er EINVAL
193The file referenced by
194.Fa fd
195is not a directory, or
196.Fa nbytes
197is too small for returning a directory entry or block of entries,
198or the current position pointer is invalid.
199.It Bq Er EIO
200An
201.Tn I/O
202error occurred while reading from or writing to the file system.
203.El
204.Sh SEE ALSO
205.Xr lseek 2 ,
206.Xr open 2 ,
207.Xr opendir 3 ,
208.Xr dirent 5
209.Sh HISTORY
210The
211.Fn getdirentries
212function first appeared in
213.Bx 4.4 .
214