10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
104 lines
1.8 KiB
Groff
104 lines
1.8 KiB
Groff
.TH DIRREAD 3
|
|
.SH NAME
|
|
dirread, dirreadall \- read directory
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
long dirread(int fd, Dir **buf)
|
|
.PP
|
|
.B
|
|
long dirreadall(int fd, Dir **buf)
|
|
.PP
|
|
.B
|
|
#define STATMAX 65535U
|
|
.PP
|
|
.B
|
|
#define DIRMAX (sizeof(Dir)+STATMAX)
|
|
.SH DESCRIPTION
|
|
The data returned by a
|
|
.MR read 3
|
|
on a directory is a set of complete directory entries
|
|
in a machine-independent format, exactly equivalent to
|
|
the result of a
|
|
.MR stat 3
|
|
on each file or subdirectory in the directory.
|
|
.I Dirread
|
|
decodes the directory entries into a machine-dependent form.
|
|
It reads from
|
|
.IR fd
|
|
and unpacks the data into an array of
|
|
.B Dir
|
|
structures
|
|
whose address is returned in
|
|
.B *buf
|
|
(see
|
|
.MR stat 3
|
|
for the layout of a
|
|
.BR Dir ).
|
|
The array is allocated with
|
|
.MR malloc 3
|
|
each time
|
|
.I dirread
|
|
is called.
|
|
.PP
|
|
.I Dirreadall
|
|
is like
|
|
.IR dirread ,
|
|
but reads in the entire directory; by contrast,
|
|
.I dirread
|
|
steps through a directory one
|
|
.MR read 3
|
|
at a time.
|
|
.PP
|
|
Directory entries have variable length.
|
|
A successful
|
|
.I read
|
|
of a directory always returns an integral number of complete directory entries;
|
|
.I dirread
|
|
always returns complete
|
|
.B Dir
|
|
structures.
|
|
See
|
|
.IR read (9p)
|
|
for more information.
|
|
.PP
|
|
The constant
|
|
.B STATMAX
|
|
is the maximum size that a directory entry can occupy.
|
|
The constant
|
|
.B DIRMAX
|
|
is an upper limit on the size necessary to hold a
|
|
.B Dir
|
|
structure and all the associated data.
|
|
.PP
|
|
.I Dirread
|
|
and
|
|
.I dirreadall
|
|
return the number of
|
|
.B Dir
|
|
structures filled in
|
|
.BR buf .
|
|
The file offset is advanced by the number of bytes actually read.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/dirread.c
|
|
.SH SEE ALSO
|
|
.MR intro 3 ,
|
|
.MR open 3 ,
|
|
.MR read 3
|
|
.SH DIAGNOSTICS
|
|
.I Dirread
|
|
and
|
|
.I Dirreadall
|
|
return zero for end of file and a negative value for error.
|
|
In either case,
|
|
.B *buf
|
|
is set to
|
|
.B nil
|
|
so the pointer can always be freed with impunity.
|
|
.PP
|
|
These functions set
|
|
.IR errstr .
|