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

FreeBSD Manual Pages


home | help
GETDIRENTRIES(2)	    BSD	System Calls Manual	      GETDIRENTRIES(2)

     getdirentries, getdents --	get directory entries in a file	system inde-
     pendent format

     Standard C	Library	(libc, -lc)

     #include <sys/types.h>
     #include <dirent.h>

     getdirentries(int fd, char	*buf, size_t nbytes, off_t *basep);

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

     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).  Some file
     systems may not support these system calls	with buffers smaller than this

     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)) have
     the same d_fileno.	 The d_off field returns a cookie which	can be used
     with lseek(2) 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	re-
     trieved 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 (getdirentries() only), a	value returned in the d_off field, or

     The d_off field is	being used as a	cookie to readdir for nfs servers.
     These cookies can be cached and allow to read directory entries at	a spe-
     cific offset on demand.

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

     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 allo-
			cated 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

     [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.

     lseek(2), open(2)

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

BSD				March 30, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help