dirstat(2) — AIX PS/2 1.2.1



DIRSTAT(2,L)                AIX Technical Reference                DIRSTAT(2,L)



-------------------------------------------------------------------------------
dirstat



PURPOSE

Gets file status information for multiple files in a directory.

SYNTAX

#include <sys/dirstat.h>

int dirstat (fildes, buf, bufsize)
int fildes;
struct dirstat *buf;
unsigned int bufsize;

DESCRIPTION

The dirstat system call returns status information on multiple files within a
directory.  Its arguments are a file descriptor to a directory which has been
opened for reading, a pointer to a buffer, and the size of the buffer in bytes.
The buffer should be large enough to hold at least one dirstat structure and
one NAME_MAX + 1 (256) byte character string.  On each call, dirstat packs as
many dirstat structures as possible into the user's buffer, and advances the
file pointer associated with fildes.  It returns a count of the number of
structures in the buffer, unless an error occurs, in which case a -1 is
returned and the file pointer is not advanced.

When dirstat encounters a symbolic link, the link is not followed and status
information about the link itself is returned.  Similarly, dirstat does not
slide through a hidden directory; status information about the hidden directory
itself is returned.  When dirstat encounters a mount point, status information
is returned for the root directory of the mounted file system.  In particular,
when performing a dirstat call on the root directory of a mounted file system,
both the "." and ".." entries correspond to the root directory of the mounted
file system.

If dirstat encounters an error while attempting to get the file status of some
particular inode within the directory, it marks the corresponding dirstat
structure's dir_stat.st_ss field with a -1 and sets dir_stat.st_errno to the
error number encountered.  The only other fields valid when the dir_stat.st_ss
field is -1 are dir_nam_len, dir_rec_len, dir_stat.st_ino, and the directory
entry name returned by DIRST_NAME() macro.

The structure which dirstat returns is given below.  The fields of the stat
structure (dir_stat) are described in "stat.h." The dir_nam_len field gives the
length of the name, including the trailing null character.  In general, dirstat
uses less than NAME_MAX characters for the name.  Instead, dirstat puts the
next structure on the first four-byte boundary following the null-terminated
name field of the current structure.  This makes it impossible to access the



Processed November 7, 1990       DIRSTAT(2,L)                                 1



DIRSTAT(2,L)                AIX Technical Reference                DIRSTAT(2,L)



buffer as an array of dirstat structures.  Programmers should use the DIRST_ADV
macro provided in dirstat.h to advance a pointer through the list of
structures.  This macro uses the dir_rec_len field to allow for future
expansion of the dirstat structure without requiring the recompilation of old
programs.

Programmers should use the DIRST_NAME macro provided in dirstat.h to obtain the
name associated with a particular entry in the list.  The macro takes a pointer
to an entry in the list, and returns a pointer to the associated name.  This
macro should always be used to access the name, since it uses the dir_rec_len
field to allow for future expansion of the dirstat structure without requiring
the recompilation of old programs.

The dirstat structure is given below:

short dir_nam_len;           Length of name
short dir_rec_len;           Length of dirstat structure and name
struct stat dir_stat;        Stat structure similar to that returned by statx

RETURN VALUE

Upon successful completion, a count of dirstat structures in the buffer is
returned.  Otherwise, a value of -1 is returned and errno is set to indicate
the error.

ERROR CONDITIONS

The dirstat system call fails if one or more of the following are true:

EFAULT    buf points outside the process's allocated address space.

EBADF     fildes is not a valid open file descriptor.

ENOTDIR   fildes is not a file descriptor for a directory open for read.

ESITEDN1  The site or sites on which the directory is stored are now down.

EINVAL    bufsize is smaller than the smallest legal return value, that is,
          smaller than the size of struct dirstat plus the space required for
          the smallest legal file name.

ENAMETOOLONG
          The directory contains a file whose name plus a dirstat structure
          does not fit in the provided bufsize bytes.  This error cannot occur
          if bufsize is at least the size of struct dirstat + NAME_MAX + 1.

Errors returned in dir_stat.st_errno correspond to those returned by statx, see
"statx, fstatx, stat, fstat, fullstat, ffullstat, lstat."

RELATED INFORMATION





Processed November 7, 1990       DIRSTAT(2,L)                                 2



DIRSTAT(2,L)                AIX Technical Reference                DIRSTAT(2,L)



In this book:  "stat.h" and "statx, fstatx, stat, fstat, fullstat, ffullstat,
lstat."





















































Processed November 7, 1990       DIRSTAT(2,L)                                 3

Museum

Related Articles