---
name: "getdirentries"
section: "2"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/getdents"
---

# getdirentries(2)

get directory entries in a file system independent format

Part of [getdents(2)](/getdents/2.md).

## NAME

**getdirentries**, **getdents** – get directory entries in a file system independent format

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<dirent.h\>**

*ssize\_t*\

**getdirentries**(*int fd*, *char \*buf*, *size\_t nbytes*, *off\_t \*basep*);

*ssize\_t*\

**getdents**(*int fd*, *char \*buf*, *size\_t 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:

```
ino_t     d_fileno;
off_t     d_off;
uint16_t  d_reclen;
uint8_t   d_type;
uint16_t  d_namlen;
char      d_name[MAXNAMLEN + 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\_off* field returns a cookie which, if non-zero, can be used with [lseek(2)](/lseek/2.md) to position the directory descriptor to the next entry. 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 *\<sys/dirent.h\>*. 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 MAXNAMLEN + 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.

If the *basep* pointer value is non-NULL, 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), a value returned in the *d\_off* field if it is non-zero, or zero.

## IMPLEMENTATION NOTES

The *d\_off* field is currently set to 0 by the NFS client, since the directory offset cookies returned by an NFS server cannot be used by [lseek(2)](/lseek/2.md) at this time.

## 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 non-NULL *basep* point outside the allocated address space.

- \[EINVAL\]

  The value of *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.

- \[EINTEGRITY\]

  Corrupted data was detected while reading from the file system.

- \[ENOENT\]

  Directory unlinked but still open.

- \[ENOTDIR\]

  The file referenced by *fd* is not a directory.

## SEE ALSO

[lseek(2)](/lseek/2.md), [open(2)](/open/2.md), [directory(3)](/directory/3.md), [dir(5)](/dir/5.md)

## HISTORY

The **getdirentries**() system call first appeared in 4.4BSD. The **getdents**() system call first appeared in FreeBSD 3.0.