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 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 refrenced 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
Hewlett-Packard Company - 1 - HP-UX Release 11i: November 2000
directory(3C) directory(3C)
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 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 stream, result has the value NULL. An error
number is returned upon 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:
Hewlett-Packard Company - 2 - HP-UX Release 11i: November 2000
directory(3C) directory(3C)
[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.
[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() or readdir_r() 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.
Hewlett-Packard Company - 3 - HP-UX Release 11i: November 2000
directory(3C) directory(3C)
[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.
[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
Hewlett-Packard Company - 4 - HP-UX Release 11i: November 2000
directory(3C) directory(3C)
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. <ndir.h> header
file is obsoleted starting from HP-UX 10.30 and is available in
/usr/old/usr/include directory.
New applications should use the <dirent.h> header file for portability
to System V and X/Open systems. The <ndir.h> header file is obsoleted
starting from HP-UX 10.30 and is going to be removed in future
releases.
readdir() is unsafe in multithread applications. closedir(),
opendir(), readdir(), rewinddir(), seekdir() and readdir_r() are
thread-safe. These interfaces are not async-cancel-safe. A
cancellation point may occur when a thread is executing closedir(),
opendir(), readdir(), rewinddir(), seekdir() or readdir_r().
Users of readdir_r() should note that readdir_r() now conforms with
the POSIX.1c Threads standard. The old prototype of readdir_r() is
supported for compatibility with existing DCE applications only.
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).
STANDARDS CONFORMANCE
closedir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
opendir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
readdir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
readdir_r(): POSIX.1c
rewinddir(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
seekdir(): AES, SVID3, XPG2, XPG3, XPG4
telldir(): AES, XPG2, XPG3, XPG4
Hewlett-Packard Company - 5 - HP-UX Release 11i: November 2000
|
