1.\" Copyright (c) 1989, 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.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95
| 1.\" Copyright (c) 1989, 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.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95
|
33.\" $FreeBSD: head/lib/libc/sys/getdirentries.2 107788 2002-12-12 17:26:04Z ru $
| 33.\" $FreeBSD: head/lib/libc/sys/getdirentries.2 108028 2002-12-18 09:22:32Z ru $
|
34.\"
35.Dd May 3, 1995
36.Dt GETDIRENTRIES 2
37.Os
38.Sh NAME
39.Nm getdirentries ,
40.Nm getdents
41.Nd "get directory entries in a file system independent format"
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In sys/types.h
46.In dirent.h
47.Ft int
48.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
49.Ft int
50.Fn getdents "int fd" "char *buf" "int nbytes"
51.Sh DESCRIPTION
52The
53.Fn getdirentries
54and
55.Fn getdents
| 34.\"
35.Dd May 3, 1995
36.Dt GETDIRENTRIES 2
37.Os
38.Sh NAME
39.Nm getdirentries ,
40.Nm getdents
41.Nd "get directory entries in a file system independent format"
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In sys/types.h
46.In dirent.h
47.Ft int
48.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
49.Ft int
50.Fn getdents "int fd" "char *buf" "int nbytes"
51.Sh DESCRIPTION
52The
53.Fn getdirentries
54and
55.Fn getdents
|
56functions read directory entries from the directory
| 56system calls read directory entries from the directory
|
57referenced by the file descriptor
58.Fa fd
59into the buffer pointed to by
60.Fa buf ,
61in a file system independent format.
62Up to
63.Fa nbytes
64of data will be transferred.
65The
66.Fa nbytes
67argument must be greater than or equal to the
68block size associated with the file,
69see
70.Xr stat 2 .
| 57referenced by the file descriptor
58.Fa fd
59into the buffer pointed to by
60.Fa buf ,
61in a file system independent format.
62Up to
63.Fa nbytes
64of data will be transferred.
65The
66.Fa nbytes
67argument must be greater than or equal to the
68block size associated with the file,
69see
70.Xr stat 2 .
|
71Some file systems may not support these functions
| 71Some file systems may not support these system calls
|
72with buffers smaller than this size.
73.Pp
74The data in the buffer is a series of
75.Em dirent
76structures each containing the following entries:
77.Bd -literal -offset indent
78u_int32_t d_fileno;
79u_int16_t d_reclen;
80u_int8_t d_type;
81u_int8_t d_namlen;
82char d_name[MAXNAMELEN + 1]; /* see below */
83.Ed
84.Pp
85The
86.Fa d_fileno
87entry is a number which is unique for each
88distinct file in the file system.
89Files that are linked by hard links (see
90.Xr link 2 )
91have the same
92.Fa d_fileno .
93The
94.Fa d_reclen
95entry is the length, in bytes, of the directory record.
96The
97.Fa d_type
98entry is the type of the file pointed to by the directory record.
99The file type values are defined in
100.Fa <sys/dirent.h> .
101The
102.Fa d_name
103entry contains a null terminated file name.
104The
105.Fa d_namlen
106entry specifies the length of the file name excluding the null byte.
107Thus the actual size of
108.Fa d_name
109may vary from 1 to
110.Dv MAXNAMELEN
111\&+ 1.
112.Pp
113Entries may be separated by extra space.
114The
115.Fa d_reclen
116entry may be used as an offset from the start of a
117.Fa dirent
118structure to the next structure, if any.
119.Pp
120The actual number of bytes transferred is returned.
121The current position pointer associated with
122.Fa fd
123is set to point to the next block of entries.
124The pointer may not advance by the number of bytes returned by
125.Fn getdirentries
126or
127.Fn getdents .
128A value of zero is returned when
129the end of the directory has been reached.
130.Pp
131The
132.Fn getdirentries
| 72with buffers smaller than this size.
73.Pp
74The data in the buffer is a series of
75.Em dirent
76structures each containing the following entries:
77.Bd -literal -offset indent
78u_int32_t d_fileno;
79u_int16_t d_reclen;
80u_int8_t d_type;
81u_int8_t d_namlen;
82char d_name[MAXNAMELEN + 1]; /* see below */
83.Ed
84.Pp
85The
86.Fa d_fileno
87entry is a number which is unique for each
88distinct file in the file system.
89Files that are linked by hard links (see
90.Xr link 2 )
91have the same
92.Fa d_fileno .
93The
94.Fa d_reclen
95entry is the length, in bytes, of the directory record.
96The
97.Fa d_type
98entry is the type of the file pointed to by the directory record.
99The file type values are defined in
100.Fa <sys/dirent.h> .
101The
102.Fa d_name
103entry contains a null terminated file name.
104The
105.Fa d_namlen
106entry specifies the length of the file name excluding the null byte.
107Thus the actual size of
108.Fa d_name
109may vary from 1 to
110.Dv MAXNAMELEN
111\&+ 1.
112.Pp
113Entries may be separated by extra space.
114The
115.Fa d_reclen
116entry may be used as an offset from the start of a
117.Fa dirent
118structure to the next structure, if any.
119.Pp
120The actual number of bytes transferred is returned.
121The current position pointer associated with
122.Fa fd
123is set to point to the next block of entries.
124The pointer may not advance by the number of bytes returned by
125.Fn getdirentries
126or
127.Fn getdents .
128A value of zero is returned when
129the end of the directory has been reached.
130.Pp
131The
132.Fn getdirentries
|
133function writes the position of the block read into the location pointed to by
| 133system call writes the position of the block read into the location pointed to by
|
134.Fa basep .
135Alternatively, the current position pointer may be set and retrieved by
136.Xr lseek 2 .
137The current position pointer should only be set to a value returned by
138.Xr lseek 2 ,
139a value returned in the location pointed to by
140.Fa basep
| 134.Fa basep .
135Alternatively, the current position pointer may be set and retrieved by
136.Xr lseek 2 .
137The current position pointer should only be set to a value returned by
138.Xr lseek 2 ,
139a value returned in the location pointed to by
140.Fa basep
|
141.Pf ( Fn getdirentries
| 141.Fn ( getdirentries
|
142only)
143or zero.
144.Sh RETURN VALUES
145If successful, the number of bytes actually transferred is returned.
146Otherwise, -1 is returned and the global variable
147.Va errno
148is set to indicate the error.
149.Sh ERRORS
| 142only)
143or zero.
144.Sh RETURN VALUES
145If successful, the number of bytes actually transferred is returned.
146Otherwise, -1 is returned and the global variable
147.Va errno
148is set to indicate the error.
149.Sh ERRORS
|
150.Fn Getdirentries
| 150The
151.Fn getdirentries
152system call
|
151will fail if:
152.Bl -tag -width Er
153.It Bq Er EBADF
154.Fa fd
155is not a valid file descriptor open for reading.
156.It Bq Er EFAULT
157Either
158.Fa buf
159or
160.Fa basep
161point outside the allocated address space.
162.It Bq Er EINVAL
163The file referenced by
164.Fa fd
165is not a directory, or
166.Fa nbytes
167is too small for returning a directory entry or block of entries,
168or the current position pointer is invalid.
169.It Bq Er EIO
170An
171.Tn I/O
172error occurred while reading from or writing to the file system.
173.El
174.Sh SEE ALSO
175.Xr lseek 2 ,
176.Xr open 2
177.Sh HISTORY
178The
179.Fn getdirentries
| 153will fail if:
154.Bl -tag -width Er
155.It Bq Er EBADF
156.Fa fd
157is not a valid file descriptor open for reading.
158.It Bq Er EFAULT
159Either
160.Fa buf
161or
162.Fa basep
163point outside the allocated address space.
164.It Bq Er EINVAL
165The file referenced by
166.Fa fd
167is not a directory, or
168.Fa nbytes
169is too small for returning a directory entry or block of entries,
170or the current position pointer is invalid.
171.It Bq Er EIO
172An
173.Tn I/O
174error occurred while reading from or writing to the file system.
175.El
176.Sh SEE ALSO
177.Xr lseek 2 ,
178.Xr open 2
179.Sh HISTORY
180The
181.Fn getdirentries
|
180function first appeared in
| 182system call first appeared in
|
181.Bx 4.4 .
182The
183.Fn getdents
| 183.Bx 4.4 .
184The
185.Fn getdents
|
184function first appeared in
| 186system call first appeared in
|
185.Fx 3.0 .
| 187.Fx 3.0 .
|