1 .TH DIRREAD 3
2 .SH NAME
3 dirread, dirreadall \- read directory
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 long dirread(int fd, Dir **buf)
11 .PP
12 .B
13 long dirreadall(int fd, Dir **buf)
14 .PP
15 .B
16 #define	STATMAX	65535U
17 .PP
18 .B
19 #define	DIRMAX	(sizeof(Dir)+STATMAX)
20 .SH DESCRIPTION
21 The data returned by a
22 .MR read (3)
23 on a directory is a set of complete directory entries
24 in a machine-independent format, exactly equivalent to
25 the result of a
26 .MR stat (3)
27 on each file or subdirectory in the directory.
28 .I Dirread
29 decodes the directory entries into a machine-dependent form.
30 It reads from
31 .IR fd
32 and unpacks the data into an array of
33 .B Dir
34 structures
35 whose address is returned in
36 .B *buf
37 (see
38 .MR stat (3)
39 for the layout of a
40 .BR Dir ).
41 The array is allocated with
42 .MR malloc (3)
43 each time
44 .I dirread
45 is called.
46 .PP
47 .I Dirreadall
48 is like
49 .IR dirread ,
50 but reads in the entire directory; by contrast,
51 .I dirread
52 steps through a directory one
53 .MR read (3)
54 at a time.
55 .PP
56 Directory entries have variable length.
57 A successful
58 .I read
59 of a directory always returns an integral number of complete directory entries;
60 .I dirread
61 always returns complete
62 .B Dir
63 structures.
64 See
65 .IR read (9p)
66 for more information.
67 .PP
68 The constant
69 .B STATMAX
70 is the maximum size that a directory entry can occupy.
71 The constant
72 .B DIRMAX
73 is an upper limit on the size necessary to hold a
74 .B Dir
75 structure and all the associated data.
76 .PP
77 .I Dirread
78 and
79 .I dirreadall
80 return the number of
81 .B Dir
82 structures filled in
83 .BR buf .
84 The file offset is advanced by the number of bytes actually read.
85 .SH SOURCE
86 .B \*9/src/lib9/dirread.c
87 .SH SEE ALSO
88 .MR intro (3) ,
89 .MR open (3) ,
90 .MR read (3)
91 .SH DIAGNOSTICS
92 .I Dirread
93 and
94 .I Dirreadall
95 return zero for end of file and a negative value for error.
96 In either case,
97 .B *buf
98 is set to
99 .B nil
100 so the pointer can always be freed with impunity.
101 .PP
102 These functions set
103 .IR errstr .