June 9, 1993 GETDIRENTRIES 3

### NAME

getdirentries - get directory entries in a filesystem independent format

### SYNOPSIS

```int` getdirentries(```int fd``, char *buf``, int nbytes``, long *basep`)

### DESCRIPTION

This interface is provided for compatibility only and has been obsoleted by getdents(2).

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`. If ```d_fileno` is zero, the entry refers to a deleted file.

The ```d_reclen` entry is the length, in bytes, of the directory record.

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.

The ```d_name` entry contains a null terminated file name.

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 VALUES

If successful, the number of bytes actually transferred is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

### ERRORS

getdirentries(``) will fail if:

[```EBADF`]
  ```fd` is not a valid file descriptor open for reading.

[```EFAULT`]
  Either ```buf` or ```basep` point outside the allocated address space.

[```EIO`]
  An I/O error occurred while reading from or writing to the file system.

### SEE ALSO

lseek(2), open(2)

### HISTORY

The getdirentries(``) function first appeared in 4.4BSD.