--- name: "getdirentries" section: "2" platform: "linux" package: "freebsd-manpages" version: "6.0-5" release: "Debian 4.0 (Etch)" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/getdirentries" --- # getdirentries(2) get directory entries in a file system independent format ## NAME **getdirentries**, **getdents** – get directory entries in a file system independent format ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** **#include \** *int*\ **getdirentries**(*int fd*, *char \*buf*, *int nbytes*, *long \*basep*); *int*\ **getdents**(*int fd*, *char \*buf*, *int nbytes*); ## DESCRIPTION The **getdirentries**() and **getdents**() system calls read directory entries from the directory referenced by the file descriptor *fd* into the buffer pointed to by *buf*, in a file system independent format. Up to *nbytes* of data will be transferred. The *nbytes* argument must be greater than or equal to the block size associated with the file, see [stat(2)](/stat/2.md). Some file systems may not support these system calls with buffers smaller than this size. The data in the buffer is a series of *dirent* structures each containing the following entries: ``` u_int32_t d_fileno; u_int16_t d_reclen; u_int8_t d_type; u_int8_t 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 file system. Files that are linked by hard links (see [link(2)](/link/2.md)) have the same *d\_fileno*. The *d\_reclen* entry is the length, in bytes, of the directory record. The *d\_type* entry is the type of the file pointed to by the directory record. The file type values are defined in *\*. 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**() or **getdents**(). A value of zero is returned when the end of the directory has been reached. The **getdirentries**() system call 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)](/lseek/2.md). The current position pointer should only be set to a value returned by [lseek(2)](/lseek/2.md), a value returned in the location pointed to by *basep* **(**(*getdirentries*) only) 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 The **getdirentries**() system call will fail if: - \[EBADF\] The *fd* argument is not a valid file descriptor open for reading. - \[EFAULT\] Either *buf* or *basep* point outside the allocated address space. - \[EINVAL\] The file referenced by *fd* is not a directory, or *nbytes* is too small for returning a directory entry or block of entries, or the current position pointer is invalid. - \[EIO\] An I/O error occurred while reading from or writing to the file system. ## SEE ALSO [lseek(2)](/lseek/2.md), [open(2)](/open/2.md) ## HISTORY The **getdirentries**() system call first appeared in 4.4BSD. The **getdents**() system call first appeared in FreeBSD 3.0.