## NAME

ACE_Dirent - Define a portable UNIX directory-entry iterator.

## SYNOPSIS

    #include <ace/Dirent.h>

    class ACE_Dirent
    {
      public:
        ACE_Dirent (void);
        ACE_Dirent (const char *dirname);
        int open (const char *filename);
        ~ACE_Dirent (void);
        void close (void);
        dirent *read (void);
        int read (struct dirent *entry, struct dirent **result);
        long tell (void);
        void seek (long loc);
        void rewind (void);
      private:
        DIR *dirp_;
    };

## DESCRIPTION

Define a portable directory-entry manipulation interface.

## Initialization and termination methods.

    ACE_Dirent (void);

Default constructor.

    ACE_Dirent (const char *dirname);

Constructor calls `opendir`

    int open (const char *filename);

Opens the directory named by filename and associates a directory stream with it.

    ~ACE_Dirent (void);

Destructor calls `closedir`.

    void close (void);

Closes the directory stream and frees the DIR structure.

## Iterator methods.

    dirent *read (void);

Returns a pointer to a structure representing the directory entry at the current position in the directory stream to which dirp refers, and positions the directory stream at the next entry, except on read-only filesystems. It returns a NULL pointer upon reaching the end of the directory stream, or upon detecting an invalid location in the directory. `readdir` shall not return directory entries containing empty names. It is unspecified whether entries are returned for dot or dot-dot. The pointer returned by `readdir` points to data that may be overwritten by another call to `readdir` on the same directory stream. This data shall not be overwritten by another call to readdir() on a different directory stream. `readdir` may buffer several directory entries per actual read operation; `readdir` marks for update the st_atime field of the directory each time the directory is actually read.

    int read (struct dirent *entry, struct dirent **result);

Has the equivalent functionality as `readdir` except that an `entry` and `result` buffer must be supplied by the caller to store the result.

## Manipulators.

    long tell (void);

Returns the current location associated with the directory stream.

    void seek (long loc);

Sets the position of the next `readdir` operation on the directory stream. The new position reverts to the position associated with the directory stream at the time the `telldir` operation that provides loc was performed. Values 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.

    void rewind (void);

Resets the position of the directory stream to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to `opendir` would.

## AUTHOR

Douglas C. Schmidt `schmidt@cs.wustl.edu`

## LIBRARY

ace