directory(3C)                                       directory(3C)



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

SYNOPSIS
     #include <dirent.h>

     DIR *opendir (const char *filename);

     struct dirent *readdir (DIR *dirp);

     long telldir (DIR *dirp);

     void seekdir (DIR *dirp, long loc);

     void rewinddir (DIR *dirp);

     int closedir (DIR *dirp);

DESCRIPTION
     opendir opens the directory named by filename and associates
     a directory stream with it.  opendir returns a pointer to be
     used to identify the directory stream in  subsequent  opera-
     tions.   The  directory  stream  is  positioned at the first
     entry.  The NULL pointer is returned if filename  cannot  be
     accessed  or  is not a directory, or if it cannot malloc(3C)
     enough memory to hold a DIR structure or a  buffer  for  the
     directory entries.

     readdir returns a pointer to the next active directory entry
     and  positions  the  directory stream at the next entry.  No
     inactive entries are returned.  It returns NULL upon  reach-
     ing  the  end  of the directory or upon detecting an invalid
     location in the directory.  readdir buffers  several  direc-
     tory  entries  per  actual read operation; readdir marks for
     update the statime field of the  directory  each  time  the
     directory is actually read.

     telldir returns the current  location  associated  with  the
     named directory stream.

     seekdir sets the position of the next readdir  operation  on
     the directory stream.  The new position reverts to the posi-
     tion associated  with  directory  stream  at  the  time  the
     telldir  operation  that provides loc was performed.  Values
     returned by telldir are valid only if the directory has  not
     changed  because of compaction or expansion.  This situation
     is not a problem with System V, but it may be a problem with
     some file system types.

     rewinddir resets the position of the named directory  stream
     to  the  beginning  of  the  directory.   It also causes the



                                                                1

directory(3C)                                       directory(3C)



     directory stream to  refer  to  the  current  state  of  the
     corresponding directory, as a call to opendir would.

     closedir closes the named directory stream and frees the DIR
     structure.   The  following  errors can occur as a result of
     these operations.

     opendir returns NULL on failure and sets errno to one of the
     following values:

     ENOTDIR             A component of filename is not a  direc-
                         tory.

     EACCES              A component of  filename  denies  search
                         permission.

     EACCES              Read permission is denied on the  speci-
                         fied directory.

     EMFILE              The maximum number of  file  descriptors
                         are currently open.

     ENFILE              The system file table is full.

     EFAULT              filename points  outside  the  allocated
                         address space.

     ELOOP               Too many symbolic links were encountered
                         in translating filename.

     ENAMETOOLONG        The  length  of  the  filename  argument
                         exceeds  {PATH_MAX},  or the length of a
                         filename  component  exceeds  {NAME_MAX}
                         while (_POSIX_NO_TRUNC) is in effect.

     ENOENT              A component of filename does  not  exist
                         or  is a null pathname.  readdir returns
                         NULL on failure and sets errno to one of
                         the following values:

     ENOENT              The current file pointer for the  direc-
                         tory is not located at a valid entry.

     EBADF               The file descriptor  determined  by  the
                         DIR  stream  is  no  longer valid.  This
                         result occurs if the DIR stream has been
                         closed.  telldir, seekdir, and  closedir
                         return -1 on failure and  set  errno  to
                         the following value:

     EBADF               The file descriptor  determined  by  the
                         DIR  stream  is  no  longer valid.  This



                                                                2

directory(3C)                                       directory(3C)



                         results  if  the  DIR  stream  has  been
                         closed.

EXAMPLE
     Here is a sample program that prints the names  of  all  the
     files in the current directory:

          #include <stdio.h>
          #include <dirent.h>

          main()
          {
               DIR *dirp;
               struct dirent *direntp;

               dirp = opendir( "." );
               while ( (direntp = readdir( dirp )) != NULL )
                    (void)printf( "%s\n", direntp->dname );
               closedir( dirp );
               return (0);
          }

SEE ALSO
     getdents(2), dirent(4)

NOTES
     rewinddir is implemented as a macro, so its function address
     cannot be taken.



























                                                                3