tools/llvm: Do not build with symbols
[minix3.git] / lib / libc / sys / getdents.2
blob4bd01ceb6a45dbfa654c82dffc24ec23f154c263
1 .\"     $NetBSD: getdents.2,v 1.23 2011/07/20 17:51:25 njoly 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. Neither the name of the University nor the names of its contributors
15 .\"    may be used to endorse or promote products derived from this software
16 .\"    without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\"     @(#)getdirentries.2     8.1 (Berkeley) 6/9/93
31 .\"
32 .Dd June 4, 2010
33 .Dt GETDENTS 2
34 .Os
35 .Sh NAME
36 .Nm getdents
37 .Nd "get directory entries in a filesystem independent format"
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In dirent.h
42 .Ft int
43 .Fn getdents "int fd" "char *buf" "size_t nbytes"
44 .Sh DESCRIPTION
45 .Fn getdents
46 reads directory entries from the directory
47 referenced by the file descriptor
48 .Fa fd
49 into the buffer pointed to by
50 .Fa buf ,
51 in a filesystem independent format.
52 Up to
53 .Fa nbytes
54 of data will be transferred.
55 .Fa nbytes
56 must be greater than or equal to the
57 block size associated with the file,
58 see
59 .Xr stat 2 .
60 Some filesystems may not support
61 .Fn getdents
62 with buffers smaller than this size.
63 .Pp
64 The data in the buffer is a series of
65 .Em dirent
66 structures:
67 .Bd -literal -offset indent
68 struct dirent {
69         ino_t    d_fileno;              /* file number of entry */
70         uint16_t d_reclen;              /* length of this record */
71         uint16_t d_namlen;              /* length of d_name */
72         uint8_t  d_type;                /* file type, see below */
73         char     d_name[MAXNAMELEN + 1];
75 .Ed
76 .Pp
77 The structure is described in
78 .Xr dirent 3 .
79 .Pp
80 Entries may be separated by extra space.
81 The
82 .Fa d_reclen
83 entry may be used as an offset from the start of a
84 .Fa dirent
85 structure to the next structure, if any.
86 .Pp
87 The actual number of bytes transferred is returned.
88 The current position pointer associated with
89 .Fa fd
90 is set to point to the next block of entries.
91 The pointer may not advance by the number of bytes returned by
92 .Fn getdents .
93 A value of zero is returned when
94 the end of the directory has been reached.
95 .Pp
96 The current position pointer may be set and retrieved by
97 .Xr lseek 2 .
98 The current position pointer should only be set to a value returned by
99 .Xr lseek 2 ,
100 or zero.
101 .Sh RETURN VALUES
102 If successful, the number of bytes actually transferred is returned.
103 Otherwise, \-1 is returned and the global variable
104 .Va errno
105 is set to indicate the error.
106 .Sh ERRORS
107 .Fn getdents
108 will fail if:
109 .Bl -tag -width "[EINVAL]"
110 .It Bq Er EBADF
111 .Fa fd
112 is not a valid file descriptor open for reading.
113 .It Bq Er EFAULT
114 .Fa buf
115 points outside the allocated address space.
116 .It Bq Er EINVAL
117 A directory was being read on NFS, but it was modified on the server while
118 it was being read.
119 .It Bq Er EIO
121 .Tn I/O
122 error occurred while reading from or writing to the file system.
124 .Sh SEE ALSO
125 .Xr lseek 2 ,
126 .Xr open 2 ,
127 .Xr dirent 3
128 .Sh HISTORY
130 .Fn getdents
131 function first appeared in
132 .Nx 1.3 .