xref: /386bsd/usr/share/man/cat2/getdirentries.0 (revision a2142627) 
1GETDIRENTRIES(2)          386BSD Programmer's Manual          GETDIRENTRIES(2)
2
3NNAAMMEE
4     ggeettddiirreennttrriieess - get directory entries in a filesystem independent format
5
6SSYYNNOOPPSSIISS
7     ##iinncclluuddee <<ssyyss//ddiirreenntt..hh>>
8
9     _i_n_t
10     ggeettddiirreennttrriieess(_i_n_t _f_d, _c_h_a_r *_b_u_f, _i_n_t _n_b_y_t_e_s, _l_o_n_g *_b_a_s_e_p)
11
12DDEESSCCRRIIPPTTIIOONN
13     GGeettddiirreennttrriieess() reads directory entries from the directory referenced by
14     the file descriptor _f_d into the buffer pointed to by _b_u_f, in a filesystem
15     independent format.  Up to _n_b_y_t_e_s of data will be transferred.  _N_b_y_t_e_s
16     must be greater than or equal to the block size associated with the file,
17     see stat(2).  Some filesystems may not support ggeettddiirreennttrriieess() with
18     buffers smaller than this size.
19
20     The data in the buffer is a series of _d_i_r_e_n_t structures each containing
21     the following entries:
22
23           unsigned long   d_fileno;
24           unsigned short  d_reclen;
25           unsigned short  d_namlen;
26           char            d_name[MAXNAMELEN + 1]; /* see below */
27
28     The _d__f_i_l_e_n_o entry is a number which is unique for each distinct file in
29     the filesystem.  Files that are linked by hard links (see link(2))  have
30     the same _d__f_i_l_e_n_o. The _d__r_e_c_l_e_n entry is the length, in bytes, of the
31     directory record.  The _d__n_a_m_e entry contains a null terminated file name.
32     The _d__n_a_m_l_e_n entry specifies the length of the file name excluding the
33     null byte.  Thus the actual size of _d__n_a_m_e may vary from 1 to MAXNAMELEN
34     + 1.
35
36     Entries may be separated by extra space.  The _d__r_e_c_l_e_n entry may be used
37     as an offset from the start of a _d_i_r_e_n_t structure to the next structure,
38     if any.
39
40     The actual number of bytes transferred is returned.  The current position
41     pointer associated with _f_d is set to point to the next block of entries.
42     The pointer may not advance by the number of bytes returned by
43     ggeettddiirreennttrriieess().  A value of zero is returned when the end of the
44     directory has been reached.
45
46     GGeettddiirreennttrriieess() writes the position of the block read into the location
47     pointed to by _b_a_s_e_p. Alternatively, the current position pointer may be
48     set and retrieved by lseek(2).  The current position pointer should only
49     be set to a value returned by lseek(2),  a value returned in the location
50     pointed to by _b_a_s_e_p, or zero.
51
52RREETTUURRNN VVAALLUUEESS
53     If successful, the number of bytes actually transferred is returned.
54     Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to
55     indicate the error.
56
57EERRRROORRSS
58     GGeettddiirreennttrriieess() will fail if:
59
60     EBADF     _f_d is not a valid file descriptor open for reading.
61
62     EFAULT    Either _b_u_f or _b_a_s_e_p point outside the allocated address space.
63
64     EIO       An I/O error occurred while reading from or writing to the file
65               system.
66
67SSEEEE AALLSSOO
68     open(2),  lseek(2)
69
70HHIISSTTOORRYY
71     The ggeettddiirreennttrriieess function call is currently under development.
72
73BSD Experimental                 July 23, 1991                               2
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133