dirread.3 (1898B)
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 .