getdents(2)							   getdents(2)

NAME    [Toc]    [Back]

     getdents, getdents64, ngetdents, ngetdents64 - read directory entries and
     put in a file system independent format

C SYNOPSIS    [Toc]    [Back]

     #include <sys/dirent.h>

     int getdents(int fildes, dirent_t *buf, unsigned nbyte);

     int getdents64(int	fildes,	dirent64_t *buf, unsigned nbyte);

     int ngetdents(int fildes, dirent_t	*buf, unsigned nbyte, int *eof);

     int ngetdents64(int fildes, dirent64_t *buf, unsigned nbyte, int *eof);

DESCRIPTION    [Toc]    [Back]

     fildes is a file descriptor obtained from a creat,	open, dup, fcntl,
     pipe, or ioctl system call.

     getdents attempts to read nbyte bytes from	the directory associated with
     fildes and	to format them as file system independent directory entries in
     the buffer	pointed	to by buf.  Since the file system independent
     directory entries are of variable length, in most cases the actual	number
     of	bytes returned will be strictly	less than nbyte. See dirent(4) to
     calculate the number of bytes.

     The file system independent directory entry is specified by the dirent
     structure.	 For a description of this see dirent(4).

     getdents starts at	a position in the file given by	the file pointer
     associated	with fildes.  Upon return from getdents, the file pointer is
     incremented to point to the next directory	entry.

     This system call was developed in order to	implement the readdir routine
     [for a description, see directory(3C)], and should	not be used for	other
     purposes.

     getdents64	is identical to	getdents except	that the dirent64_t structure
     is	used instead of	the dirent_t structure.	 The dirent64_t	structure can
     return larger values for some fields.

     ngetdents and ngetdents64 are identical to	getdents and getdents64,
     respectively, except that the eof argument	is present.  The value pointed
     to	by eof is set to 1 if end-of-file was encountered during the current
     operation,	0 otherwise.  Use of this feature eliminates the necessity to
     call getdents one more time (and get 0 returned) after the	last data is
     returned.

     getdents will fail	if one or more of the following	are true:






									Page 1






getdents(2)							   getdents(2)



     EBADF	    fildes is not a valid file descriptor open for reading.

     EFAULT	    buf	points outside the allocated address space.

     EINVAL	    nbyte is not large enough for one directory	entry.

     ENOENT	    The	current	file pointer for the directory is not located
		    at a valid entry.

     ENOLINK	    fildes points to a remote machine and the link to that
		    machine is no longer active.  is located on	a remote file
		    system which is not	available [see intro(2)].

     ETIMEDOUT	    fildes refers to a directory on a remote file system which
		    is not available [see intro(2)].

     ENOTDIR	    fildes is not a directory.

     EIO	    An I/O error occurred while	accessing the file system.

     EDIRCORRUPTED  The	directory is corrupted in the file system.

SEE ALSO    [Toc]    [Back]

     directory(3C), dirent(4)

DIAGNOSTICS    [Toc]    [Back]

     Upon successful completion	a non-negative integer is returned indicating
     the number	of bytes actually read.	 A value of 0 indicates	the end	of the
     directory has been	reached.  If the system	call failed, a -1 is returned
     and errno is set to indicate the error.


									PPPPaaaaggggeeee 2222