| DIRREAD(3) | DIRREAD(3)
| NAME
| dirread, dirreadall – read directory
SYNOPSIS
| `#include <u.h> #include <libc.h>
` `long dirread(int fd, Dir **buf)
` `long dirreadall(int fd, Dir **buf)
` `#define STATMAX 65535U
` `#define DIRMAX (sizeof(Dir)+STATMAX)`
DESCRIPTION
| The data returned by a read(3) on a directory is a set of complete directory entries in a machine-independent format, exactly equivalent to the result of a stat(3) on each file or subdirectory in the directory. Dirread decodes the directory entries into a machine-dependent form. It reads from fd and unpacks the data into an array of `Dir` structures whose address is returned in `*buf` (see stat(3) for the layout of a `Dir`). The array is allocated with malloc(3) each time dirread is called.
Dirreadall is like dirread, but reads in the entire directory; by contrast, dirread steps through a directory one read(3) at a time.
Directory entries have variable length. A successful read of a directory always returns an integral number of complete directory entries; dirread always returns complete `Dir` structures. See read(9p) for more information.
The constant `STATMAX` is the maximum size that a directory entry can occupy. The constant `DIRMAX` is an upper limit on the size necessary to hold a `Dir` structure and all the associated data.
Dirread and dirreadall return the number of `Dir` structures filled in `buf`. The file offset is advanced by the number of bytes actually read.
SOURCE
| `/usr/local/plan9/src/lib9/dirread.c`
SEE ALSO
| intro(3), open(3), read(3)
DIAGNOSTICS
| Dirread and Dirreadall return zero for end of file and a negative value for error. In either case, `*buf` is set to `nil` so the pointer can always be freed with impunity.
These functions set errstr.