libc/sys/getdirentries.2

         Copyright (c) 1989 The Regents of the University of California.
 All rights reserved.

 Redistribution and use in source and binary forms are permitted
 provided that the above copyright notice and this paragraph are
 duplicated in all such forms and that any documentation,
 advertising materials, and other materials related to such
 distribution and use acknowledge that the software was developed
 by the University of California, Berkeley. The name of the
 University may not be used to endorse or promote products derived
 from this software without specific prior written permission.
 THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
 IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

 @(#)getdirentries.2 6.1 (Berkeley) 06/06/89

 GETDIRENTRIES 2 ""
C 7  NAME
getdirentries - get directory entries in a filesystem independent format
 SYNOPSIS
#include <sys/dirent.h>

cc = getdirentries(fd, buf, nbytes, basep)
int cc, fd;
char *buf;
int nbytes;
long *basep;

 DESCRIPTION
 Getdirentries reads directory entries from the directory
referenced by the file descriptor
 fd into the buffer pointed to by
 buf , in a filesystem independent format.
Up to
 nbytes of data will be transferred.
 Nbytes must be greater than or equal to the
block size associated with the file,
see
 stat(2) . Some filesystems may not support
 getdirentries with buffers smaller than this size.

The data in the buffer is a series of
 dirent structures each containing the following entries:


unsigned long d_fileno;
unsigned short d_reclen;
unsigned short d_namlen;
char d_name[MAXNAMELEN + 1]; /* see below */


The
 d_fileno entry is a number which is unique for each
distinct file in the filesystem.
Files that are linked by hard links (see
 link(2) ) have the same
 d_fileno . The
 d_reclen entry is the length, in bytes, of the directory record.
The
 d_name entry contains a null terminated file name.
The
 d_namlen entry specifies the length of the file name excluding the null byte.
Thus the actual size of
 d_name may vary from 1 to MAXNAMELEN + 1.

Entries may be separated by extra space.
The
 d_reclen entry may be used as an offset from the start of a
 dirent structure to the next structure, if any.

The actual number of bytes transferred is returned.
The current position pointer associated with
 fd is set to point to the next block of entries.
The pointer may not advance by the number of bytes returned by
 getdirentries . A value of zero is returned when
the end of the directory has been reached.

 Getdirentries writes the position of the block read into the location pointed to by
 basep . Alternatively, the current position pointer may be set and retrieved by
 lseek(2) . The current position pointer should only be set to a value returned by
 lseek(2) , a value returned in the location pointed to by
 basep , or zero.
 RETURN VALUE
If successful, the number of bytes actually transferred is returned.
Otherwise, a -1 is returned and the global variable
 errno is set to indicate the error.
 ERRORS
 Getdirentries will fail if one or more of the following are true:
 15
EBADF
fd is not a valid file descriptor open for reading.
 15
EFAULT
Either buf or basep point outside the allocated address space.
 15
EIO
An I/O error occurred while reading from or writing to the file system.
 "SEE ALSO"
open(2), lseek(2)