readdir man page on DigitalUNIX

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

opendir(3)							    opendir(3)

NAME
       opendir,	 readdir,  readdir_r,  telldir, seekdir, rewinddir, closedir -
       Perform operations on directories

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

       DIR *opendir(
	       const char *dir_name ); struct dirent *readdir(
	       DIR *dir_pointer ); int readdir_r(
	       DIR *dir_pointer,
	       struct dirent *entry,
	       struct dirent **result ); long telldir(
	       DIR *dir_pointer ); void seekdir(
	       DIR *dir_pointer,
	       long location ); void rewinddir(
	       DIR *dir_pointer ); int closedir(
	       DIR *dir_pointer );

       The following function does not conform to current  industry  standards
       and is supported only for backward compatibility:

       int readdir_r(
	       DIR *dir_pointer,
	       struct dirent *result );

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       closedir(): POSIX.1, XPG4, XPG4-UNIX

       opendir(): POSIX.1, XPG4, XPG4-UNIX

       readdir(): POSIX.1c, XPG4, XPG4-UNIX

       readdir_r(): POSIX.1c

       rewinddir(): POSIX.1, XPG4, XPG4-UNIX

       seekdir(): POSIX.1, XPG4, XPG4-UNIX

       telldir(): POSIX.1, XPG4, XPG4-UNIX

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

PARAMETERS
       Names  the  directory.  If the final component of dir_name names a sym‐
       bolic link, the link will be traversed  and  pathname  resolution  will
       continue.  Points to the dir structure of an open directory.  Points to
       the storage location that will hold the entry.  Specifies the number of
       an  entry  relative  to	the start of the directory.  Contains the next
       directory entry on return from the readdir_r() function.	 Set equal  to
       entry  upon  successful completion or to NULL on error or end-of-direc‐
       tory.

DESCRIPTION
       The opendir() function opens the directory designated by	 the  dir_name
       parameter  and  associates  a  directory	 stream with it. The directory
       stream is positioned at the first entry. The type DIR, which is defined
       in the dirent.h header file, represents a directory stream, which is an
       ordered sequence of all the directory entries in	 a  particular	direc‐
       tory.  If  a file descriptor is used, the FD_CLOEXEC option will be set
       on that file descriptor.

       The opendir() function also returns a pointer to identify the directory
       stream  in subsequent operations. The null pointer is returned when the
       directory named by the dir_name parameter cannot be  accessed  or  when
       not enough memory is available to hold the entire stream.

       The  type DIR, which is defined in the dirent.h header file, represents
       a directory stream, which is an ordered sequence of all	the  directory
       entries	in  a particular directory. Directory entries represent files;
       files may be removed from a directory or added  to  a  directory	 asyn‐
       chronously to the operation of the readdir() function.

       The  readdir()  function	 returns a pointer to a structure representing
       the directory entry at the current position  in	the  directory	stream
       specified  by  the  dir_pointer	parameter, and positions the directory
       stream at the next entry. It returns a null pointer upon	 reaching  the
       end  of	the  directory	stream.	 The  dirent  structure defined in the
       dirent.h header file 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 the readdir() function points to data which may
       be overwritten by another call  to  readdir()  on  the  same  directory
       stream.	This data will not be 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 the opendir() or rewinddir() function, whether a subse‐
       quent call to the readdir() function returns an entry for that file  is
       unspecified.

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

       When it reaches the end of the directory, or when it detects an invalid
       seekdir() operation, the readdir() function returns the null value.

       The telldir() function returns the current location associated with the
       specified directory stream.

       The  seekdir()  function sets the position of the next readdir() opera‐
       tion on the directory stream specified by the dir_pointer parameter  to
       the position specified by the location parameter.

       If  the	value  of the location parameter was not returned by a call to
       the telldir() function, or if there was	an  intervening	 call  to  the
       rewinddir() function on this directory stream, the effect is undefined.
       The new position reverts to  the	 one  associated  with	the  directory
       stream when the telldir() operation was performed.

       An attempt to seek to an invalid location causes the readdir() function
       to return the null value the next time  it  is  called.	 The  position
       should be that returned by a previous telldir() function call.

       The rewinddir() function resets the position of the specified directory
       stream to the beginning of the directory. It also causes the  directory
       stream to refer to the current state of the corresponding directory, as
       a call to the opendir() function would have done.  If  the  dir_pointer
       parameter  does	not  refer  to a directory stream, the effect is unde‐
       fined.

       The closedir() function closes a directory stream and frees the	struc‐
       ture  associated with the dir_pointer parameter. Upon return, the value
       of dir_pointer may no longer point to an accessible object of the  type
       DIR.   If  a  file  descriptor is used to implement type DIR, that file
       descriptor will be closed.

       [POSIX]	The readdir_r() function is the reentrant version of the read‐
       dir()  function.	 The  readdir_r()  function  stores the next directory
       entry at entry, and returns entry in result.  On end-of-directory, NULL
       is stored in result and 0 (zero) is returned.

NOTES
       An open directory must always be closed with the closedir() function to
       ensure that the next attempt to open that directory is successful.

       The use of the seekdir() and telldir() functions is not recommended  in
       the Tru64 UNIX operating system, as the results can be unpredictable.

       [POSIX] The  readdir function is not supported for multithreaded appli‐
       cations. Instead, its reentrant equivalent, readdir_r, should  be  used
       with multiple threads.

RETURN VALUES
       Upon successful completion, the opendir() function returns a pointer to
       an object of type DIR. Otherwise, null is returned  and	errno  set  to
       indicate the error.

       Upon successful completion, the readdir() function returns 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.

       Upon  successful completion, the telldir() function returns the current
       location. Otherwise, -1 is returned.

       Upon successful completion, the closedir() function returns  0  (zero).
       Otherwise, -1 is returned.

       [POSIX]	Upon  successful completion or end-of-directory, the readd_r()
       function returns 0 (zero). Otherwise, an error number is returned.

       [Tru64 UNIX]  Upon successful completion, the obsolete version  of  the
       readdir_r() function returns 0 (zero). Otherwise, -1 is returned.

ERRORS
       If the opendir() function fails, errno may be set to one of the follow‐
       ing values: Search permission is denied for any component  of  dir_name
       or read permission is denied for dir_name.  Too many links were encoun‐
       tered in translating dir_name.	The  length  of	 the  dir_name	string
       exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.  The
       dir_name parameter points to the name of a file that does not exist, or
       the  parameter  points  to an empty string.  A component of dir_name is
       not a directory.

EXAMPLES
       To search a directory for the entry name:

       len =  strlen(name);  dir_pointer  =  opendir(".");  for	 (dp  =	 read‐
       dir(dir_pointer); dp != NULL; dp =      readdir(dir_pointer))
	       if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
		       closedir(dir_pointer);
		       return FOUND;
	       }

       closedir(dir_pointer); return NOT_FOUND;

SEE ALSO
       Functions: close(2), lseek(2), open(2), read(2), scandir(3)

       Standards: standards(5)

								    opendir(3)
[top]

List of man pages available for DigitalUNIX

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