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