| 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.