Commit | Line | Data |
---|---|---|
0b0a22c4 KM |
1 | .\" Copyright (c) 1989 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms are permitted | |
5 | .\" provided that the above copyright notice and this paragraph are | |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
15 | .\" | |
16 | .\" @(#)getdirentries.2 6.1 (Berkeley) %G% | |
17 | .\" | |
18 | .TH GETDIRENTRIES 2 "" | |
19 | .UC 7 | |
20 | .SH NAME | |
21 | getdirentries \- get directory entries in a filesystem independent format | |
22 | .SH SYNOPSIS | |
23 | .nf | |
24 | .ft B | |
25 | #include <sys/dirent.h> | |
26 | .LP | |
27 | .ft B | |
28 | cc = getdirentries(fd, buf, nbytes, basep) | |
29 | int cc, fd; | |
30 | char *buf; | |
31 | int nbytes; | |
32 | long *basep; | |
33 | .fi | |
34 | .SH DESCRIPTION | |
35 | .I Getdirentries | |
36 | reads directory entries from the directory | |
37 | referenced by the file descriptor | |
38 | .I fd | |
39 | into the buffer pointed to by | |
40 | .IR buf , | |
41 | in a filesystem independent format. | |
42 | Up to | |
43 | .I nbytes | |
44 | of data will be transferred. | |
45 | .I Nbytes | |
46 | must be greater than or equal to the | |
47 | block size associated with the file, | |
48 | see | |
49 | .IR stat(2) . | |
50 | Some filesystems may not support | |
51 | .I getdirentries | |
52 | with buffers smaller than this size. | |
53 | .PP | |
54 | The data in the buffer is a series of | |
55 | .I dirent | |
56 | structures each containing the following entries: | |
57 | .PP | |
58 | .RS | |
59 | .ta +\w'unsigned\0short\0'u +\w'd_name[MAXNAMELEN + 1];\0'u | |
60 | .nf | |
61 | unsigned long d_fileno; | |
62 | unsigned short d_reclen; | |
63 | unsigned short d_namlen; | |
64 | char d_name[MAXNAMELEN + 1]; /* see below */ | |
65 | .fi | |
66 | .RE | |
67 | .PP | |
68 | The | |
69 | .I d_fileno | |
70 | entry is a number which is unique for each | |
71 | distinct file in the filesystem. | |
72 | Files that are linked by hard links (see | |
73 | .IR link(2) ) | |
74 | have the same | |
75 | .IR d_fileno . | |
76 | The | |
77 | .I d_reclen | |
78 | entry is the length, in bytes, of the directory record. | |
79 | The | |
80 | .I d_name | |
81 | entry contains a null terminated file name. | |
82 | The | |
83 | .I d_namlen | |
84 | entry specifies the length of the file name excluding the null byte. | |
85 | Thus the actual size of | |
86 | .I d_name | |
87 | may vary from 1 to \fBMAXNAMELEN + 1\fP. | |
88 | .PP | |
89 | Entries may be separated by extra space. | |
90 | The | |
91 | .I d_reclen | |
92 | entry may be used as an offset from the start of a | |
93 | .I dirent | |
94 | structure to the next structure, if any. | |
95 | .PP | |
96 | The actual number of bytes transferred is returned. | |
97 | The current position pointer associated with | |
98 | .I fd | |
99 | is set to point to the next block of entries. | |
100 | The pointer may not advance by the number of bytes returned by | |
101 | .IR getdirentries . | |
102 | A value of zero is returned when | |
103 | the end of the directory has been reached. | |
104 | .PP | |
105 | .I Getdirentries | |
106 | writes the position of the block read into the location pointed to by | |
107 | .IR basep . | |
108 | Alternatively, the current position pointer may be set and retrieved by | |
109 | .IR lseek(2) . | |
110 | The current position pointer should only be set to a value returned by | |
111 | .I lseek(2) , | |
112 | a value returned in the location pointed to by | |
113 | .I basep , | |
114 | or zero. | |
115 | .SH RETURN VALUE | |
116 | If successful, the number of bytes actually transferred is returned. | |
117 | Otherwise, a \-1 is returned and the global variable | |
118 | .I errno | |
119 | is set to indicate the error. | |
120 | .SH ERRORS | |
121 | .I Getdirentries | |
122 | will fail if one or more of the following are true: | |
123 | .TP 15 | |
124 | EBADF | |
125 | \fIfd\fP is not a valid file descriptor open for reading. | |
126 | .TP 15 | |
127 | EFAULT | |
128 | Either \fIbuf\fP or \fIbasep\fP point outside the allocated address space. | |
129 | .TP 15 | |
130 | EIO | |
131 | An I/O error occurred while reading from or writing to the file system. | |
132 | .SH "SEE ALSO" | |
133 | open(2), lseek(2) |