directory(S)                   6 January 1993                   directory(S)


 Name

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

 Syntax


    cc  . . .  -lc


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

    void closedir(dirp)
    DIR *dirp;

    DIR *opendir (filename)
    char *filename;

    struct dirent *readdir (dirp)
    DIR *dirp;

    void rewinddir (dirp)
    DIR *dirp;

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

    long telldir (dirp)
    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 operations.  The pointer NULL is returned
    if filename cannot be accessed or is not a directory, or if it cannot
    malloc enough memory to hold a DIR structure or a buffer for the direc-
    tory entries.

    readdir returns a pointer to the next active directory entry.  No inac-
    tive entries are returned.  It returns NULL upon reaching the end of the
    directory or upon detecting an invalid location in the directory.

    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, loc, is the position associated with the
    directory stream when the telldir operation was performed.  Values
    returned by telldir are good only if the directory has not changed due to
    compaction or expansion.  This is not a problem with System V, but it may
    be with some file system types.

    rewinddir resets the position of the named directory stream to the begin-
    ning of the directory.

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

    The following errors can occur as a result of these operations.

    opendir:

    [EACCES]    A component of filename denies search permission.

    [EFAULT]    filename points outside the allocated address space.

    [EMFILE]    The maximum number of file descriptors are currently open.

    [ENOTDIR]   A component of filename is not a directory.

    readdir:

    [EBADF]     The file descriptor determined by the DIR stream is no longer
                valid.  This results if the DIR stream has been closed.

    [ENOENT]    The current file pointer for the directory is not located at
                a valid entry.

    closedir:

    [EBADF]     The dirp argument does not refer to an open directory stream.

    [EINTR]     The closedir function was interrupted by a signal.


 Example

    Sample code which searches a directory for entry name:

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


 Warnings

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

 See also

    dirent(FP), getdents(S)

 Standards conformance

    closedir, opendir, readdir and rewinddir are conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.

    seekdir and telldir are conformant with:
    AT&T SVID Issue 2;
    and X/Open Portability Guide, Issue 3, 1989.