HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/!!!intro.3c
________________________________________________________________
___ ___
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. 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()
initializesthe dirent structure refrenced by entry to represent the current position in
the directory stream referenced by dirp, and stores a pointer to this structure at the loca-
tion 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 structdirent 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
Section 3−−144 − 1 − HP-UX Release 11i: December 2000
___
___