Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GETDENTS(2)		  FreeBSD System Calls Manual		   GETDENTS(2)

NAME
     getdents -- get directory entries in a filesystem independent format

SYNOPSIS
     #include <dirent.h>

     int
     getdents(int fd, void *buf, size_t	nbytes);

DESCRIPTION
     getdents()	reads directory	entries	from the directory referenced by the
     file descriptor fd	into the buffer	pointed	to by buf, in a	filesystem in-
     dependent 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 getdents() with buffers
     smaller than this size.

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

	   ino_t	   d_fileno;
	   off_t	   d_off;
	   u_int16_t	   d_reclen;
	   u_int8_t	   d_type;
	   u_int8_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 filesystem.  Files that are linked by hard links (see link(2))	have
     the same d_fileno.	 The d_off entry is the	file offset of the next	entry.
     The d_reclen entry	is the length, in bytes, of the	directory record.

     The d_type	is the type of file, where the following are possible types:
     DT_UNKNOWN, DT_FIFO, DT_CHR, DT_DIR, DT_BLK, DT_REG, DT_LNK, and DT_SOCK.

     The d_namlen entry	specifies the length of	the file name excluding	the
     NUL byte.	Thus the actual	size of	d_name may vary	from 1 to MAXNAMLEN +
     1.

     The d_name	entry contains a NUL-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.

     Invalid entries with d_fileno set to 0 may	be returned among regular en-
     tries.

     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
     getdents().

     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), the value of d_off from an entry, or zero.

RETURN VALUES
     If	successful, the	number of bytes	actually transferred is	returned.  A
     value of zero is returned when the	end of the directory has been reached.
     Otherwise,	-1 is returned and the global variable errno is	set to indi-
     cate the error.

ERRORS
     getdents()	will fail if:

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

     [EFAULT]		Part of	buf points outside the process's allocated ad-
			dress 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), open(2),	opendir(3), dirent(5)

STANDARDS
     The getdents() call is not	a portable interface and should	not be used
     directly by applications.	Use readdir(3) instead.

HISTORY
     The getdirentries() function first	appeared in 4.4BSD.  In	OpenBSD	5.5
     the d_off entry was added to struct dirent	and getdirentries() was	re-
     placed with getdents().

FreeBSD	13.0		       December	16, 2014		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getdents&sektion=2&manpath=OpenBSD+6.9>

home | help