readdir man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

READDIR(3C)							   READDIR(3C)

NAME
       readdir, readdir_r - read directory

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

       struct dirent *readdir(DIR *dirp);

       struct dirent *readdir_r(DIR *dirp, struct dirent *entry);

   Standard conforming
       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

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

DESCRIPTION
       The  type  DIR, which is defined in the header <dirent.h>, represents a
       directory stream, which is an ordered sequence  of  all	the  directory
       entries	in  a particular directory. Directory entries represent files.
       Files can be removed from a directory or added  to  a  directory	 asyn‐
       chronously to the operation of readdir() and readdir_r().

   readdir()
       The  readdir()  function	 returns a pointer to a structure representing
       the directory entry at the current position  in	the  directory	stream
       specified  by  the argument dirp, and positions the directory stream at
       the next entry.	It returns a null pointer upon reaching the end of the
       directory stream. The structure dirent defined by the <dirent.h> header
       describes a directory entry.

       The readdir() function will not	return	directory  entries  containing
       empty  names.  If  entries for . (dot) or .. (dot-dot) exist, one entry
       will be returned for dot and one entry will be  returned	 for  dot-dot;
       otherwise they will not be returned.

       The  pointer returned by readdir() points to data that can be overwrit‐
       ten by another call to readdir() on the same  directory	stream.	 These
       data  are  not  overwritten by another call to readdir() on a different
       directory stream.

       If a file is removed from or added to  the  directory  after  the  most
       recent  call to opendir(3C) or rewinddir(3C), whether a subsequent call
       to readdir() returns an entry for that file is unspecified.

       The readdir() function can buffer several directory entries per	actual
       read operation. It marks for update the st_atime field of the directory
       each time the directory is actually read.

       After a call to fork(2), either the parent or child (but not both)  can
       continue	 processing  the directory stream using readdir(), rewinddir()
       or seekdir(3C). If both the parent and child processes use these	 func‐
       tions, the result is undefined.

       If  the	entry  names a symbolic link, the value of the d_ino member is
       unspecified.

   readdir_r()
       Unless the end of the directory stream has been	reached	 or  an	 error
       occurred,  the  readdir_r()  function  initializes the dirent structure
       referenced by entry to represent the directory  entry  at  the  current
       position	 in  the  directory stream referred to by dirp,	 and positions
       the directory stream at the next entry.

       The caller must allocate storage pointed to by entry to be large enough
       for  a  dirent structure with an array of char d_name member containing
       at least NAME_MAX (that is, pathconf(directory, _PC_NAME_MAX)) plus one
       elements. (_PC_NAME_MAX is defined in <unistd.h>.)

       The  readdir_r()	 function will not return directory entries containing
       empty names. It is unspecified whether entries are returned for . (dot)
       or ..  (dot-dot).

       If  a  file  is	removed	 from or added to the directory after the most
       recent call to opendir() or rewinddir(), whether a subsequent  call  to
       readdir_r() returns an entry for that file is unspecified.

       The  readdir_r()	 function  can	buffer	several	 directory entries per
       actual read operation. It marks for update the st_atime	field  of  the
       directory each time the directory is actually read.

       The  standard-conforming	 version (see standards(5)) of the readdir_r()
       function performs all of the  actions  described	 above	and  sets  the
       pointer	pointed	 to  by	 result. If a directory entry is returned, the
       pointer will be set to the same value as the entry argument; otherwise,
       it will be set to NULL.

RETURN VALUES
       Upon  successful	 completion,  readdir()	 and  the  default readdir_r()
       return a pointer to an object of type struct dirent. When an  error  is
       encountered,  a	null  pointer is returned and errno is set to indicate
       the error. When the end of the directory is encountered, a null pointer
       is returned and errno is not changed.

       The standard-conforming readdir_r() returns  0 if the end of the direc‐
       tory is encountered or a directory entry is  stored  in	the  structure
       referenced by entry. Otherwise, an error number is returned to indicate
       the failure.

ERRORS
       The readdir() and readdir_r() functions will fail if:

       EOVERFLOW
		    One of the values in the structure to be  returned	cannot
		    be represented correctly.

       The readdir() and readdir_r() functions may fail if:

       EBADF
		 The dirp argument does not refer to an open directory stream.

       ENOENT
		 The current position of the directory stream is invalid.

USAGE
       The  readdir()  and readdir_r() functions should be used in conjunction
       with opendir(), closedir(), and rewinddir() to examine the contents  of
       the  directory.	 Since	readdir() and the default readdir_r() return a
       null pointer both at the end of the directory and on error, an applica‐
       tion wanting to check for error situations should set errno to 0 before
       calling either of these functions. If  errno  is	 set  to  non-zero  on
       return, an error occurred.

       It  is safe to use readdir() in a threaded application, so long as only
       one thread reads from the directory stream at any given time. The read‐
       dir() function is generally preferred over the readdir_r() function.

       The  standard-conforming	 readdir_r()  returns  the  error number if an
       error occurred. It returns 0 on success (including reaching the end  of
       the directory stream).

       The  readdir()  and  readdir_r() functions have transitional interfaces
       for 64-bit file offsets.	 See lf64(5).

EXAMPLES
       Example 1 Search the current directory for the entry name.

       The following sample program will search the current directory for each
       of the arguments supplied on the command line:

	 #include <sys/types.h>
	 #include <dirent.h>
	 #include <errno.h>
	 #include <stdio.h>
	 #include <strings.h>

	 static void lookup(const char *arg)
	 {
		 DIR *dirp;
		 struct dirent *dp;

		 if ((dirp = opendir(".")) == NULL) {
			 perror("couldn't open '.'");
			 return;
		 }

		 do {
			 errno = 0;
			 if ((dp = readdir(dirp)) != NULL) {
				 if (strcmp(dp->d_name, arg) != 0)
					 continue;

				 (void) printf("found %s\n", arg);
				 (void) closedir(dirp);
				 return;
			 }
		 } while (dp != NULL);

		 if (errno != 0)
			 perror("error reading directory");
		 else
			 (void) printf("failed to find %s\n", arg);
		 (void) closedir(dirp);
		 return;
	 }

	 int main(int argc, char *argv[])
	 {
		 int i;
		 for (i = 1; i < argc; i++)
			 lookup(argv[i]);
		 return (0);
	 }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Standard	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ See below.      │
       └────────────────────┴─────────────────┘

       The readdir() function is Unsafe. The readdir_r() function is Safe.

SEE ALSO
       fork(2),	 lstat(2),  symlink(2),	 Intro(3),  closedir(3C), opendir(3C),
       rewinddir(3C), scandir(3C), seekdir(3C), attributes(5), lf64(5),	 stan‐
       dards(5)

NOTES
       When  compiling	multithreaded programs, see the MULTITHREADED APPLICA‐
       TIONS section of Intro(3).

       Solaris 2.4 and earlier releases provided a  readdir_r()	 interface  as
       specified  in POSIX.1c Draft 6. The final POSIX.1c standard changed the
       interface as described above. Support for the Draft 6 interface is pro‐
       vided  for  compatibility  only	and  might  not be supported in future
       releases. New applications and libraries should use  the	 standard-con‐
       forming interface.

       For  POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
       _REENTRANT  flags  are  automatically  turned  on   by	defining   the
       _POSIX_C_SOURCE flag with a value >= 199506L.

				 Jun 26, 2007			   READDIR(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net