HPUX directory[3c]
directory(3C) directory(3C)
NAME
opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir() -
directory operations
SYNOPSIS
#include <dirent.h>
DIR *opendir(const char *dirname);
struct dirent *readdir(DIR *dirp);
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 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.
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.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
directory(3C) directory(3C)
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 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.
telldir(), upon successful completion, returns a long value
indicating the current position in the directory.
Otherwise it returns -1 and sets errno to indicate the
error.
seekdir() does not return any value, but if an error is
encountered, errno is set to indicate the error.
closedir(), upon successful completion, returns a value of 0.
Otherwise, it returns a value of -1 and sets errno to
indicate the error.
ERRORS
opendir() fails if any of the following conditions are encountered:
[EACCES] Search permission is denied for a component
of dirname, or read permission is denied for
dirname.
[EFAULT] dirname points outside the allocated address
space of the process. The reliable detection
of this error is implementation dependent.
[ELOOP] Too many symbolic links were encountered in
translating the path name.
[EMFILE] Too many open file descriptors are currently
open for the calling process.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
directory(3C) directory(3C)
[ENAMETOOLONG] A component of dirname exceeds PATH_MAX
bytes, or the entire length of dirname
exceeds PATH_MAX - 1 bytes while
_POSIX_NO_TRUNC is in effect.
[ENFILE] Too many open file descriptors are currently
open on the system.
[ENOENT] A component of dirname does not exist.
[ENOMEM] malloc() failed to provide sufficient memory
to process the directory.
[ENOTDIR] A component of dirname is not a directory.
[ENOENT] The dirname argument points to an empty
string.
readdir() might fail if any of the following conditions are
encountered:
[EBADF] dirp does not refer to an open directory
stream.
[ENOENT] The directory stream to which dirp refers is
not located at a valid directory entry.
[EFAULT] dirp points outside the allocated address
space of the process.
telldir() might fail if any of the following conditions are
encountered:
[EBADF] dirp does not refer to an open directory
stream.
[ENOENT] dirp specifies an improper file system block
size.
seekdir() might fail if the following condition is encountered:
[ENOENT] dirp specifies an improper file system block
size.
closedir() might fail if any of the following conditions are
encountered:
[EBADF] dirp does not refer to an open directory
stream.
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
directory(3C) directory(3C)
[EFAULT] dirp points outside the allocated address
space of the process.
rewinddir() might fail if any of the following conditions are
encountered:
[EBADF] dirp does not refer to an open directory
stream.
[EFAULT] dirp points outside the allocated address
space of the process.
EXAMPLES
The following code searches the current directory for an entry name:
DIR *dirp;
struct dirent *dp;
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL) {
if (strcmp(dp->d_name, name) == 0) {
(void) closedir(dirp);
return FOUND;
}
}
(void) closedir(dirp);
return NOT_FOUND;
WARNINGS
readdir() and getdirentries() (see getdirentries(2) are the only ways
to access remote NFS directories. Attempting to read a remote
directory via NFS by using read() returns -1 and sets errno to EISDIR
(see read(2)).
APPLICATION USAGE
The header file required for these functions and the type of the
return value from readdir() has been changed for compatibility with
System V Release 3 and the X/Open Portability Guide. See ndir(5) for
a description of the header file <ndir.h>, which is provided to allow
existing HP-UX applications to compile unmodified.
New applications should use the <dirent.h> header file for portability
to System V and X/Open systems.
AUTHOR
directory was developed by AT&T, HP, and the University of California,
Berkeley.
SEE ALSO
close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4),
dirent(5), ndir(5).
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
directory(3C) directory(3C)
STANDARDS CONFORMANCE
closedir(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
opendir(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
readdir(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
rewinddir(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
seekdir(): AES, XPG2, XPG3, XPG4
telldir(): AES, XPG2, XPG3, XPG4
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992