Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
READDIR(3)		   Linux Programmers Manual		   READDIR(3)



NAME
       readdir, readdir_r - read a directory

SYNOPSIS
       #include 

       struct dirent *readdir(DIR *dir);

       int readdir_r(DIR *dir, struct dirent *entry, struct dirent **result);

DESCRIPTION
       The  readdir()  function returns a pointer to a dirent structure repre
       senting the next directory entry in the directory stream pointed to  by
       dir.  It returns NULL on reaching the end of the directory stream or if
       an error occurred.

       On Linux, the dirent structure is defined as follows:

	   struct dirent {
	       ino_t	      d_ino;	   /* inode number */
	       off_t	      d_off;	   /* offset to the next dirent */
	       unsigned short d_reclen;    /* length of this record */
	       unsigned char  d_type;	   /* type of file */
	       char	      d_name[256]; /* filename */
	   };

       According to POSIX, the dirent structure contains a field char d_name[]
       of  unspecified	size,  with  at most NAME_MAX characters preceding the
       terminating null byte.  POSIX.1-2001 also  documents  the  field  ino_t
       d_ino  as  an  XSI extension.  The other fields are unstandardized, and
       not present on all systems; see NOTES below for some further details.

       The data returned by readdir() may be overwritten by  subsequent  calls
       to readdir() for the same directory stream.

       The readdir_r() function is a reentrant version of readdir().  It reads
       the next directory entry from the directory stream dir, and returns  it
       in  the	caller-allocated  buffer  pointed to by entry.	(See NOTES for
       information on allocating this buffer.)	A pointer to the returned item
       is  placed  in  *result; if the end of the directory stream was encoun
       tered, then NULL is instead returned in *result.

RETURN VALUE
       The readdir() function returns a pointer to a dirent structure, or NULL
       if  an  error  occurs  or  end  of the directory stream is reached.  On
       error, errno is set appropriately.

       The readdir_r() function returns 0 on success.  On error, it returns  a
       positive  error number.	If the end of the directory stream is reached,
       readdir_r() returns 0, and returns NULL in *result.

ERRORS
       EBADF  Invalid directory stream descriptor dir.

CONFORMING TO
       SVr4, 4.3BSD, POSIX.1-2001.

NOTES
       Only the fields d_name and d_ino are specified  in  POSIX.1-2001.   The
       remaining  fields  are  available  on many, but not all systems.  Under
       glibc, programs can check  for  the  availability  of  the  fields  not
       defined in POSIX.1 by testing whether the macros _DIRENT_HAVE_D_NAMLEN,
       _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF, or  _DIRENT_HAVE_D_TYPE  are
       defined.

       Other than Linux, the d_type field is available mainly only on BSD sys
       tems.  This field makes it possible to avoid  the  expense  of  calling
       stat(2)	if  further  actions  depend  on the type of the file.	If the
       _BSD_SOURCE feature test macro is defined, then glibc defines the  fol
       lowing macro constants for the value returned in d_type:

       DT_BLK	   This is a block device.

       DT_CHR	   This is a character device.

       DT_DIR	   This is a directory.

       DT_FIFO	   This is a named pipe (FIFO).

       DT_LNK	   This is a symbolic link.

       DT_REG	   This is a regular file.

       DT_SOCK	   This is a Unix domain socket.

       DT_UNKNOWN  The file type is unknown.

       If  the	file  type  could  not	be determined, the value DT_UNKNOWN is
       returned in d_type.

       Since POSIX.1 does not specify the size of the d_name field, and  other
       non-standard fields may precede that field within the dirent structure,
       portable applications that use readdir_r() should allocate  the	buffer
       whose address is passed in entry as follows:

	   len = offsetof(struct dirent, d_name) +
		     pathconf(dirpath, _PC_NAME_MAX) + 1
	   entryp = malloc(len);

       (POSIX.1 requires that d_name is the last field in a struct dirent.)

SEE ALSO
       read(2),   closedir(3),	 dirfd(3),  ftw(3),  offsetof(3),  opendir(3),
       rewinddir(3),	 scandir(3),	 seekdir(3),	 telldir(3),	  fea
       ture_test_macros(7)

COLOPHON
       This  page  is  part of release 3.05 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.



				  2008-07-04			    READDIR(3)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:28 2009