]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/getdirentries.2
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / man / man2 / getdirentries.2
CommitLineData
9bccf70c
A
1.\" $NetBSD: getdirentries.2,v 1.7 1995/10/12 15:40:50 jtc Exp $
2.\"
3.\" Copyright (c) 1989, 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)getdirentries.2 8.1 (Berkeley) 6/9/93
35.\"
36.Dd June 9, 1993
37.Dt GETDIRENTRIES 2
38.Os
39.Sh NAME
40.Nm getdirentries
41.Nd "get directory entries in a filesystem independent format"
42.Sh SYNOPSIS
b0d623f7 43.Fd #include <dirent.h>
55e303ae
A
44.Fd #include <sys/types.h>
45.Fd #include <sys/dirent.h>
9bccf70c
A
46.Ft int
47.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
48.Sh DESCRIPTION
39037602 49.Fn getdirentries
9bccf70c
A
50reads directory entries from the directory
51referenced by the file descriptor
52.Fa fd
53into the buffer pointed to by
54.Fa buf ,
55in a filesystem independent format.
56Up to
57.Fa nbytes
58of data will be transferred.
59.Fa Nbytes
60must be greater than or equal to the
61block size associated with the file,
62see
63.Xr stat 2 .
64Some filesystems may not support
65.Fn getdirentries
66with buffers smaller than this size.
67.Pp
68The data in the buffer is a series of
69.Em dirent
6d2010ae 70structures (see
a39ff7e2
A
71.Xr dir 5)
72The order of the directory entries vended out via
73.Fn getdirentries
74is not specified. Some filesystems may return entries in lexicographic sort order
75and others may not.
9bccf70c
A
76.Pp
77The
78.Fa d_fileno
79entry is a number which is unique for each
80distinct file in the filesystem.
81Files that are linked by hard links (see
82.Xr link 2 )
83have the same
84.Fa d_fileno .
55e303ae
A
85Users of
86.Fn getdirentries
87should skip
88entries with
89.Fa d_fileno
90= 0, as such entries represent files which have been deleted but not yet removed from the directory entry.
9bccf70c
A
91The
92.Fa d_reclen
93entry is the length, in bytes, of the directory record.
94The
95.Fa d_name
96entry contains a null terminated file name.
97The
98.Fa d_namlen
99entry specifies the length of the file name excluding the null byte.
100Thus the actual size of
101.Fa d_name
102may vary from 1 to
103.Dv MAXNAMELEN
104\&+ 1.
55e303ae
A
105.Fa d_type
106is a integer representing the type of the directory entry. The following types are defined in
107.Aq sys/dirent.h :
108.Bd -literal -offset indent
109#define DT_UNKNOWN 0
110#define DT_FIFO 1
111#define DT_CHR 2
112#define DT_DIR 4
113#define DT_BLK 6
114#define DT_REG 8
115#define DT_LNK 10
116#define DT_SOCK 12
117#define DT_WHT 14
118.Ed
9bccf70c
A
119.Pp
120Entries may be separated by extra space.
121The
122.Fa d_reclen
123entry may be used as an offset from the start of a
124.Fa dirent
125structure to the next structure, if any.
126.Pp
127The actual number of bytes transferred is returned.
128The current position pointer associated with
129.Fa fd
130is set to point to the next block of entries.
131The pointer may not advance by the number of bytes returned by
132.Fn getdirentries .
133A value of zero is returned when
134the end of the directory has been reached.
135.Pp
39037602 136.Fn getdirentries
9bccf70c
A
137writes the position of the block read into the location pointed to by
138.Fa basep .
139Alternatively, the current position pointer may be set and retrieved by
140.Xr lseek 2 .
141The current position pointer should only be set to a value returned by
142.Xr lseek 2 ,
143a value returned in the location pointed to by
144.Fa basep ,
145or zero.
b0d623f7
A
146.Sh NOTES
147.Fn getdirentries
148should rarely be used directly; instead,
149.Xr opendir 3
150and
151.Xr readdir 3
152should be used.
153.Pp
154As of Mac OS X 10.6,
155.Fn getdirentries
156is deprecated, and it is recommended that applications
157use
158.Xr readdir 3
159rather than using
160.Fn getdirentries
161directly. Due to limitations with the system call,
162.Fn getdirentries
163will not work
164with 64-bit inodes; in order to use
165.Fn getdirentries ,
166.Dv _DARWIN_NO_64_BIT_INODE
6d2010ae
A
167must be defined. See
168.Xr stat 2
169for more information on
170.Dv _DARWIN_NO_64_BIT_INODE
171and its other effects.
9bccf70c
A
172.Sh RETURN VALUES
173If successful, the number of bytes actually transferred is returned.
174Otherwise, -1 is returned and the global variable
175.Va errno
176is set to indicate the error.
177.Sh ERRORS
39037602 178.Fn getdirentries
9bccf70c
A
179will fail if:
180.Bl -tag -width Er
181.It Bq Er EBADF
182.Fa fd
183is not a valid file descriptor open for reading.
184.It Bq Er EFAULT
185Either
186.Fa buf
187or
188.Fa basep
189point outside the allocated address space.
190.It Bq Er EIO
191An
192.Tn I/O
193error occurred while reading from or writing to the file system.
194.El
195.Sh SEE ALSO
2d21ac55 196.Xr lseek 2 ,
b0d623f7 197.Xr open 2 ,
6d2010ae 198.Xr stat 2 ,
b0d623f7 199.Xr opendir 3 ,
6d2010ae
A
200.Xr readdir 3 ,
201.Xr dir 5
9bccf70c
A
202.Sh HISTORY
203The
204.Fn getdirentries
205function first appeared in 4.4BSD.