mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-27 11:52:03 +00:00
977b25a76a
The overloading of IR emits magic \X'...' sequences that turn into HTML manual links. But not all such IR invocations should be manual links; those had to be written to avoid the IR macro before. Worse, the \X'...' ending the IR causes troff to emit only a single space after a period. Defining a new IM macro for manual references fixes both problems. Fixes #441.
103 lines
1.9 KiB
Groff
103 lines
1.9 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
|
|
.IM read (3)
|
|
on a directory is a set of complete directory entries
|
|
in a machine-independent format, exactly equivalent to
|
|
the result of a
|
|
.IM 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
|
|
.IM stat (3)
|
|
for the layout of a
|
|
.BR Dir ).
|
|
The array is allocated with
|
|
.IM 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
|
|
.IM 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
|
|
.IM intro (3) ,
|
|
.IM open (3) ,
|
|
.IM 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 .
|