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

d
directory(3C) directory(3C)
NAME
opendir( ), readdir( ), readdir_r( ), telldir( ), seekdir(), rewinddir( ), closedir( ) - 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.
opendir() uses malloc(3C) to allocate memory.
readdir() returns a pointer to the next directory entry. It returns a NULL pointer upon reach-
ing 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 refrenced by entry to represent the current posi-
tion 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
directory. 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 vari-
able 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 stream, result has the value NULL. An error number is returned upon
error.
Section 3−−198 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: September 2004