NAME

dirread, dirreadall − read directory

SYNOPSIS

­#include <u.h>
­#include <libc.h>

long dirread(int fd, Dir ∗∗buf)

long dirreadall(int fd, Dir ∗∗buf)

#defineSTATMAX65535U

#defineDIRMAX(sizeof(Dir)+STATMAX)

DESCRIPTION

The data returned by a read(2) on a directory is a set of complete directory entries in a machine-independent format, exactly equivalent to the result of a stat(2) 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(2) for the layout of a Dir).  The array is allocated with malloc(2) each time ­dirread is called. 

­Dirreadall is like dirread, but reads in the entire directory; by contrast, ­dirread steps through a directory one read(2) 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(5) 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

­/sys/src/libc/9sys/dirread.c

SEE ALSO

intro(2), open(2), read(2)

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.

Plan 9  —  March 02, 2002