HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

d
directory(3C) directory(3C)
NAME
directory: closedir(), opendir(), readdir(), readdir_r(), rewinddir(), seekdir(), telldir() - directory operations
SYNOPSIS
#include <dirent.h>
DIR *opendir(const char *dirname);
struct dirent *readdir(DIR *dirp);
int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);
long int telldir(DIR *dirp);
void seekdir(DIR *dirp, long int loc);
void rewinddir(DIR *dirp);
int closedir(DIR *dirp);
DESCRIPTION
This library package provides functions that allow programs to read directory entries without having to
know the actual directory format associated with the file system. Because these functions allow programs
to be used portably on file systems with different directory formats, this is the recommended way to read
directory entries.
opendir() opens the directory dirname and associates a directory stream with it. opendir()
returns a pointer used to identify the directory stream in subsequent operations. open-
dir()
uses malloc(3C) to allocate memory.
readdir() returns a pointer to the next directory entry. It returns a NULL pointer upon reaching the
end of the directory or detecting an invalid seekdir() operation. See dirent(5) for a
description of the fields available in a directory entry.
readdir_r()
initializes the dirent structure referenced by entry to represent the current position
in the directory stream referenced by dirp, and stores a pointer to this structure at the
location referenced by result.
telldir() returns the current location (encoded) associated with the directory stream to which dirp
refers.
seekdir() sets the position of the next readdir() operation on the directory stream to which dirp
refers. The loc argument is a location within the directory stream obtained from
telldir(). The position of the directory stream is restored to where it was when
telldir() returned that loc value. Values returned by telldir() are valid only
while the DIR pointer from which they are derived remains open. If the directory stream
is closed and then reopened, the telldir() value might be invalid.
rewinddir()
resets the position of the directory stream to which dirp refers to the beginning of the direc-
tory. It also causes the directory stream to refer to the current state of the corresponding
directory, as a call to opendir() would have done.
closedir() closes the named directory stream, then frees the structure associated with the DIR
pointer.
RETURN VALUE
opendir() upon successful completion, returns a pointer to an object of type DIR referring to an open
directory stream. Otherwise, it returns a NULL pointer and sets the global variable
errno to indicate the error.
readdir() upon successful completion, returns a pointer to an object of type struct dirent
describing a directory entry. Upon reaching the end of the directory, readdir() returns
a NULL pointer and does not change the value of errno. Otherwise, it returns a NULL
pointer and sets errno to indicate the error.
readdir_r()
upon successful completion returns a 0. On successful return, the pointer returned at
result has the same value as the argument entry. Upon reaching end of the directory
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−145