DIRECTORY(3C)           STANDARD C LIBRARY          DIRECTORY(3C)


NAME
     directory:  opendir,  readdir,  readdir_r, 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);

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


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.  A 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 and readdir_r marks for update the st_atime field of
     the directory each time  the  directory  is  actually  read.
     readdir  and  readdir_r  return  pointers to the next active
     directory and position the directory stream  (dirp)  at  the
     next  entry.   Both  functions  will  not  return  directory
     entries  containing  empty  names.   readdir  and  readdir_r
     buffer  several directory entries per actual read operation;
     both functions mark for update the  st_atime  field  of  the
     directory each time the directory is actually read.  On suc-
     cessful completion, readdir_r returns result.  Upon reaching
     the end of the directory string, both return a null pointer.

     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  the 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.



SUPER-UX            Last change: Oct  19, 1999                  1





DIRECTORY(3C)           STANDARD C LIBRARY          DIRECTORY(3C)


     rewinddir resets the position of the named directory  stream
     to  the  beginning  of  the  directory.   It also causes the
     directory stream to refer to the current state of the corre-
     sponding directory, as a call to opendir would.

     closedir closes the named directory stream and frees the DIR
     structure.


THREAD-SAFE
     - Multi-safe (only readdir_r)


ERRORS
     The following errors can occur as a result of  these  opera-
     tions.

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

     [ENOTDIR]    A component of filename is not a directory.
     [EACCES]     A component of filename denies  search  permis-
                  sion.
     [EACCES]     Read  permission  is  denied  on  the specified
                  directory.
     [EMFILE]     The maximum number of file descriptors are cur-
                  rently 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]
                  A component of filename exceeds the length.
     [ENOENT]     A  component of filename does not exist or is a
                  null pathname.

     readdir and readdir_r return NULL on failure and sets  errno
     to one of the following values:
     [ENOENT]     The  current  file pointer for the directory 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, and closedir return  -1  on  failure,  seekdir  not
     update dirp on failure and set errno to the following value:
     [EBADF]      The  file  descriptor  determined  by  the  DIR
                  stream is no longer valid.  This results if the
                  DIR stream has been closed.

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



SUPER-UX            Last change: Oct  19, 1999                  2





DIRECTORY(3C)           STANDARD C LIBRARY          DIRECTORY(3C)


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

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

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

REFERENCES
     dirent(4), getdents(2), mkdir(2), rmdir(2), pthreads(3T)

NOTICES
     readdir  overwrites  the  buffer  as  needed, so applications
     should copy data to preserve it.
     Use the reentrant version, readdir_r,  when  writing  multi-
     threaded applications.


































SUPER-UX            Last change: Oct  19, 1999                  3