--- name: "getdirentries" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/getdirentries" --- # getdirentries(2) get directory entries in a filesystem independent format ## NAME **getdirentries** – get directory entries in a filesystem independent format ## SYNOPSIS **#include \** **#include \** **#include \** *int*\ **getdirentries**(*int 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)](/stat/2.md). Some filesystems may not support **getdirentries**() with buffers smaller than this size. The data in the buffer is a series of *dirent* structures (see [dir(5)](/dir/5.md)) The order of the directory entries vended out via **getdirentries**() is not specified. Some filesystems may return entries in lexicographic sort order and others may not. 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)](/link/2.md)) have the same *d\_fileno*. Users of **getdirentries**() should skip entries with *d\_fileno* = 0, as such entries represent files which have been deleted but not yet removed from the directory entry. 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. NOTE: As of MacOS X 10.6, 64 bit inodes became the default for the definition of the *dirent* structure. For legacy / compatibility reasons, the older 32-bit inode definitions will support a *d\_name* length of 1 to MAXNAMELEN + 1 bytes. If 64-bit inodes are defined, the *dirent* structure will support names of up to MAXPATHLEN-1 bytes. *d\_type* is a integer representing the type of the directory entry. The following types are defined in ⟨sys/dirent.h⟩: ``` #define DT_UNKNOWN 0 #define DT_FIFO 1 #define DT_CHR 2 #define DT_DIR 4 #define DT_BLK 6 #define DT_REG 8 #define DT_LNK 10 #define DT_SOCK 12 #define DT_WHT 14 ``` 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)](/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*, or zero. ## NOTES **getdirentries**() should rarely be used directly; instead, [opendir(3)](/opendir/3.md) and [readdir(3)](/readdir/3.md) should be used. As of Mac OS X 10.6, **getdirentries**() is deprecated, and it is recommended that applications use [readdir(3)](/readdir/3.md) rather than using **getdirentries**() directly. Due to limitations with the system call, **getdirentries**() will not work with 64-bit inodes; in order to use **getdirentries**(), \_DARWIN\_NO\_64\_BIT\_INODE must be defined. See [stat(2)](/stat/2.md) for more information on \_DARWIN\_NO\_64\_BIT\_INODE and its other effects. ## 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)](/lseek/2.md), [open(2)](/open/2.md), [stat(2)](/stat/2.md), [opendir(3)](/opendir/3.md), [readdir(3)](/readdir/3.md), [dir(5)](/dir/5.md) ## HISTORY The **getdirentries**() function first appeared in 4.4BSD.