DIRECTORY(3C-SVR4)  RISC/os Reference Manual   DIRECTORY(3C-SVR4)



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



                        Printed 11/19/92                   Page 1

DIRECTORY(3C-SVR4)  RISC/os Reference Manual   DIRECTORY(3C-SVR4)



     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 opera-
     tions.

     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.





 Page 2                 Printed 11/19/92

DIRECTORY(3C-SVR4)  RISC/os Reference Manual   DIRECTORY(3C-SVR4)



     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
                         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->d_name );
               closedir( dirp );
               return (0);
          }

SEE ALSO
     getdents(2), dirent(4).

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






















                        Printed 11/19/92                   Page 3