unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

DIRECTORY(3V)                                                    DIRECTORY(3V)



NAME
       directory,  opendir,  readdir,  telldir, seekdir, rewinddir, closedir -
       directory operations

SYNOPSIS
       #include <&lt;dirent.h>&gt;

       DIR *opendir(dirname)
       char *dirname;

       struct dirent *readdir(dirp)
       DIR *dirp;

       long telldir(dirp)
       DIR *dirp;

       void seekdir(dirp, loc)
       DIR *dirp;
       long loc;

       void rewinddir(dirp)
       DIR *dirp;

       int closedir(dirp)
       DIR *dirp;

SYSTEM V SYNOPSIS
       For XPG2 conformance, use:

       #include <&lt;sys/dirent.h>&gt;

DESCRIPTION
       opendir() opens the directory named by dirname and associates a  direc-
       tory  stream  with it.  opendir() returns a pointer to be used to iden-
       tify the directory stream in subsequent operations.  A NULL pointer  is
       returned  if dirname cannot be accessed or is not a directory, or if it
       cannot malloc(3V) enough memory to hold the whole thing.

       readdir() returns a pointer to the next directory  entry.   It  returns
       NULL  upon  reaching  the  end of the directory or detecting an invalid
       seekdir() operation.

       telldir() returns the current location associated with the named direc-
       tory stream.

       seekdir()  sets  the  position  of  the next readdir() operation on the
       directory stream.  The new position reverts to the one associated  with
       the  directory stream when the telldir() operation was performed.  Val-
       ues returned by telldir() are good only for the  lifetime  of  the  DIR
       pointer  from  which  they are derived.  If the directory is closed and
       then reopened, the telldir() value may be invalidated due to undetected
       directory  compaction.   It  is  safe to use a previous telldir() value
       immediately after a call to opendir() and before any calls to readdir.

       rewinddir() resets the position of the named directory  stream  to  the
       beginning  of  the  directory.   I  also causes the directory stream to
       refer to the current state of the corresponding directory, as a call to
       opendir() would have done.

       closedir()  closes  the  named directory stream and frees the structure
       associated with the DIR pointer.

RETURN VALUES
       opendir() returns a pointer to an object of type DIR  on  success.   On
       failure, it returns NULL and sets errno to indicate the error.

       readdir()  returns a pointer to an object of type struct dirent on suc-
       cess.  On failure, it returns NULL  and  sets  errno  to  indicate  the
       error.  When the end of the directory is encountered, readdir() returns
       NULL and leaves errno unchanged.

       closedir() returns:

       0      on success.

       -1     on failure and sets errno to indicate the error.

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

ERRORS
       If any of the following conditions occur, opendir() sets errno to:

       EACCES              Search  permission  is  denied  for  a component of
                           dirname.

                           Read permission is denied for dirname.

       ENAMETOOLONG        The length of dirname exceeds {PATH_MAX}.

                           A pathname component is longer than {NAME_MAX} (see
                           sysconf(2V))  while  {_POSIX_NO_TRUNC} is in effect
                           (see pathconf(2V)).

       ENOENT              The named directory does not exist.

       ENOTDIR             A component of dirname is not a directory.

       for each of the following conditions, when the condition  is  detected,
       opendir() sets errno to one of the following:

       EMFILE              Too  many  file  descriptors are currently open for
                           the process.

       ENFILE              Too many file descriptors are currently open in the
                           system.

       For  each  of the following conditions, when the condition is detected,
       readdir() sets errno to the following:

       EBADF               dirp does not refer to an open directory stream.

       For each of the following conditions, when the condition  is  detected,
       closedir() sets errno to the following:

       EBADF               dirp does not refer to an open directory stream.

SYSTEM V ERRORS
       In addition to the above, opendir() may set errno to the following:

       ENOENT              dirname points to an empty string.

EXAMPLES
       Sample code which searchs a directory for entry ``name'' is:

                   dirp = opendir(".");
                   for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
                        if (!strcmp(dp->&gt;d_name, name)) {
                             closedir (dirp);
                             return FOUND;
                        }
                   closedir (dirp);
                   return NOT_FOUND;

SEE ALSO
       close(2V), lseek(2V), open(2V), read(2V), getwd(3), malloc(3V), dir(5)

NOTES
       The  directory library routines now use a new include file, <&lt;dirent.h>&gt;.
       This replaces the file, <&lt;sys/dir.h>&gt;, used in previous  releases.   Fur-
       thermore,  with the use of this new file, the readdir() routine returns
       directory entries whose structure is named struct  dirent  rather  than
       struct  direct  as before. The file <&lt;sys/dir.h>&gt; is retained in the cur-
       rent SunOS release for purposes of backwards source code compatibility;
       programs  which  use  the directory() library and <&lt;sys/dir.h>&gt; will con-
       tinue to compile and run without source code  modifications.   However,
       existing  programs  should  convert to the use of the new include file,
       <&lt;dirent.h>&gt;, as <&lt;sys/dir.h>&gt; will be removed in a future major release.

       The X/Open Portability Guide, issue 2  (XPG2)  requires  <&lt;sys/dirent.h>&gt;
       rather  than <&lt;dirent.h>&gt;.  /usr/xpg2include/sys/dirent.h is functionally
       equivalent to /usr/include/dirent.h.  In future SunOS releases,  X/Open
       conformance will require <&lt;dirent.h>&gt;.



                                24 January 1990                  DIRECTORY(3V)