Open System Services Library Calls Reference Manual (G06.28+, H06.05+)

OSS Library Calls (n - r) readdir(3)
NAME
readdir - Reads a directory stream
LIBRARY
G-series native OSS processes: /G/system/sysnn/zossfsrl
H-series OSS processes: /G/system/zdllnnn/zossfdll
SYNOPSIS
#include <sys/types.h> /* optional except for POSIX.1 */
#include <dirent.h>
struct dirent *readdir(
DIR *dir_pointer);
PARAMETERS
dir_pointer Points to the dir structure of an open directory.
DESCRIPTION
The type DIR, which is defined in the dirent.h header file, represents a directory stream, which
is an ordered sequence of all the directory entries in a particular directory. (Directory streams are
not implemented through file descriptors.) The structure pointed to by the dir_pointer parameter
is established by a prior call to the opendir() function.
The readdir() function returns a pointer to a structure representing the directory entry at the
current position in the directory stream specified by the dir_pointer parameter, and then positions
the directory stream at the next entry. readdir() returns a null pointer upon reaching the end of
the directory stream but does not change the value of errno. The dirent structure defined in the
dirent.h header file describes a directory entry.
The readdir() function does not return directory entries containing empty names. If entries for .
(dot) or ..(dot-dot) exist, one entry is returned for . (dot) and one entry is returned for ..(dot-dot);
otherwise, they are not returned.
The pointer returned by the readdir() function points to data that can be overwritten (or data that
is contained in a buffer that can be freed) by another call to readdir() on the same directory
stream. This data is available until another readdir() or closedir() call is made on the same
directory stream.
When one of the set of exec, tdm_exec,ortdm_spawn functions is called, all open directory
streams are closed automatically. (For calls by tdm_spawn functions, only the directory streams
of the child process are closed.) The effect is the same as if the closedir() function had been
called for each open directory stream.
If the dir_pointer parameter does not refer to a currently opened directory stream when it is
passed to the readdir() function, the following can occur:
• The error value [EBADF] or [EFAULT] might be returned.
• The caller might receive a SIGSEGV or SIGILL signal in the OSS environment.
• The caller might cause a trap condition in the Guardian environment.
• User memory might be corrupted.
General Considerations for Directory Operations
Directory entries represent files. Files can be removed from a directory or added to a directory
asynchronously to the operation of the readdir() function.
527187-007 Hewlett-Packard Company 5−69