Open System Services Library Calls Reference Manual (G06.27+, H06.04+)

telldir(3) OSS Library Calls Reference Manual
NAME
telldir - Returns current position within 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>
long telldir(
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 telldir() function returns the current location associated with the specified directory stream.
The use of the seekdir() and telldir() functions is not recommended when the possibility exists
that a directory will be modified.
If the dir_pointer parameter does not refer to a currently opened directory stream when it is
passed to the telldir() 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.
RETURN VALUES
Upon successful completion, the telldir() function returns the current location. Otherwise, the
value -1 is returned.
For Guardian disk volumes and subvolumes (directories with OSS pathnames of the form /G/vol
and /G/vol/subvol), values returned by the telldir() function are kept for use by the seekdir()
function. When the table containing these values overflows, the previous telldir() function value
becomes invalid. The seekdir() function detects this condition and sets errno to [EINVAL].
After the seekdir() function sets errno to [EINVAL], subsequent calls to the readdir() function
also set errno to [EINVAL].
When table overflow occurs but the telldir() function has not returned a value, the seekdir()
function does not detect the overflow condition or set errno to [EINVAL]. A subsequent call to
the readdir() function does not set errno to [EINVAL].
7−22 Hewlett-Packard Company 527187-004