Subversion Repositories planix.SVN

Rev

Go to most recent revision | Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH DIRREAD 2
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 
.IR read (2)
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 
.IR stat (2)
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 
.IR stat (2)
39 
for the layout of a
40 
.BR Dir ).
41 
The array is allocated with
42 
.IR malloc (2)
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 
.IR read (2)
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 (5)
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 /sys/src/libc/9sys/dirread.c
87 
.SH SEE ALSO
88 
.IR intro (2),
89 
.IR open (2),
90 
.IR read (2)
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 .