Commit | Line | Data |
---|---|---|
931b8415 | 1 | .\" Copyright (c) 1989, 1991 The Regents of the University of California. |
0b0a22c4 KM |
2 | .\" All rights reserved. |
3 | .\" | |
faf7e3e0 | 4 | .\" %sccs.include.redist.roff% |
0b0a22c4 | 5 | .\" |
faf7e3e0 | 6 | .\" @(#)getdirentries.2 6.5 (Berkeley) %G% |
0b0a22c4 | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt GETDIRENTRIES 2 | |
faf7e3e0 | 10 | .Os |
931b8415 CL |
11 | .Sh NAME |
12 | .Nm getdirentries | |
13 | .Nd "get directory entries in a filesystem independent format" | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <sys/dirent.h> | |
16 | .Ft int | |
17 | .Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" | |
18 | .Sh DESCRIPTION | |
19 | .Fn Getdirentries | |
0b0a22c4 KM |
20 | reads directory entries from the directory |
21 | referenced by the file descriptor | |
931b8415 | 22 | .Fa fd |
0b0a22c4 | 23 | into the buffer pointed to by |
931b8415 | 24 | .Fa buf , |
0b0a22c4 KM |
25 | in a filesystem independent format. |
26 | Up to | |
931b8415 | 27 | .Fa nbytes |
0b0a22c4 | 28 | of data will be transferred. |
931b8415 | 29 | .Fa Nbytes |
0b0a22c4 KM |
30 | must be greater than or equal to the |
31 | block size associated with the file, | |
32 | see | |
931b8415 | 33 | .Xr stat 2 . |
0b0a22c4 | 34 | Some filesystems may not support |
931b8415 | 35 | .Fn getdirentries |
0b0a22c4 | 36 | with buffers smaller than this size. |
931b8415 | 37 | .Pp |
0b0a22c4 | 38 | The data in the buffer is a series of |
931b8415 | 39 | .Em dirent |
0b0a22c4 | 40 | structures each containing the following entries: |
931b8415 | 41 | .Bd -literal -offset indent |
0b0a22c4 KM |
42 | unsigned long d_fileno; |
43 | unsigned short d_reclen; | |
44 | unsigned short d_namlen; | |
931b8415 CL |
45 | char d_name[MAXNAMELEN + 1]; /* see below */ |
46 | .Ed | |
47 | .Pp | |
0b0a22c4 | 48 | The |
931b8415 | 49 | .Fa d_fileno |
0b0a22c4 KM |
50 | entry is a number which is unique for each |
51 | distinct file in the filesystem. | |
52 | Files that are linked by hard links (see | |
931b8415 | 53 | .Xr link 2 ) |
0b0a22c4 | 54 | have the same |
931b8415 | 55 | .Fa d_fileno . |
0b0a22c4 | 56 | The |
931b8415 | 57 | .Fa d_reclen |
0b0a22c4 KM |
58 | entry is the length, in bytes, of the directory record. |
59 | The | |
931b8415 | 60 | .Fa d_name |
0b0a22c4 KM |
61 | entry contains a null terminated file name. |
62 | The | |
931b8415 | 63 | .Fa d_namlen |
0b0a22c4 KM |
64 | entry specifies the length of the file name excluding the null byte. |
65 | Thus the actual size of | |
931b8415 CL |
66 | .Fa d_name |
67 | may vary from 1 to | |
68 | .Dv MAXNAMELEN | |
69 | \&+ 1. | |
70 | .Pp | |
0b0a22c4 KM |
71 | Entries may be separated by extra space. |
72 | The | |
931b8415 | 73 | .Fa d_reclen |
0b0a22c4 | 74 | entry may be used as an offset from the start of a |
931b8415 | 75 | .Fa dirent |
0b0a22c4 | 76 | structure to the next structure, if any. |
931b8415 | 77 | .Pp |
0b0a22c4 KM |
78 | The actual number of bytes transferred is returned. |
79 | The current position pointer associated with | |
931b8415 | 80 | .Fa fd |
0b0a22c4 KM |
81 | is set to point to the next block of entries. |
82 | The pointer may not advance by the number of bytes returned by | |
931b8415 | 83 | .Fn getdirentries . |
0b0a22c4 KM |
84 | A value of zero is returned when |
85 | the end of the directory has been reached. | |
931b8415 CL |
86 | .Pp |
87 | .Fn Getdirentries | |
0b0a22c4 | 88 | writes the position of the block read into the location pointed to by |
931b8415 | 89 | .Fa basep . |
0b0a22c4 | 90 | Alternatively, the current position pointer may be set and retrieved by |
931b8415 | 91 | .Xr lseek 2 . |
0b0a22c4 | 92 | The current position pointer should only be set to a value returned by |
931b8415 | 93 | .Xr lseek 2 , |
0b0a22c4 | 94 | a value returned in the location pointed to by |
931b8415 | 95 | .Fa basep , |
0b0a22c4 | 96 | or zero. |
931b8415 | 97 | .Sh RETURN VALUES |
0b0a22c4 | 98 | If successful, the number of bytes actually transferred is returned. |
931b8415 CL |
99 | Otherwise, -1 is returned and the global variable |
100 | .Va errno | |
0b0a22c4 | 101 | is set to indicate the error. |
931b8415 CL |
102 | .Sh ERRORS |
103 | .Fn Getdirentries | |
104 | will fail if: | |
105 | .Bl -tag -width [EFAULT] | |
106 | .It EBADF | |
107 | .Fa fd | |
108 | is not a valid file descriptor open for reading. | |
109 | .It EFAULT | |
110 | Either | |
111 | .Fa buf | |
112 | or | |
113 | .Fa basep | |
114 | point outside the allocated address space. | |
115 | .It EIO | |
faf7e3e0 CL |
116 | An |
117 | .Tn I/O | |
118 | error occurred while reading from or writing to the file system. | |
931b8415 CL |
119 | .El |
120 | .Sh SEE ALSO | |
121 | .Xr open 2 , | |
122 | .Xr lseek 2 | |
123 | .Sh HISTORY | |
124 | The | |
faf7e3e0 CL |
125 | .Nm getdirentries |
126 | function call is | |
127 | .Ud . |