[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 2

statx, stat, lstat, fstatx, fstat, fullstat, ffullstat, stat64, lstat64, or fstat64 Subroutine

Purpose

Provides information about a file.

Library

Standard C Library (libc.a)

Syntax

#include <sys/stat.h>


int stat ( Path, Buffer)
const char *Path;
struct stat *Buffer;

int lstat (Path, Buffer)
const char *Path;
struct stat *Buffer;


int fstat ( FileDescriptor, Buffer)
int FileDescriptor;
struct stat *Buffer;


int statx (Path, Buffer, Length, Command)
char *Path;
struct stat *Buffer;
int Length;
int Command;

int fstatx (FileDescriptor, Buffer, Length, Command)
int FileDescriptor;
struct stat *Buffer;
int Length;
int Command;

#include <sys/fullstat.h>

int fullstat (Path, Command, Buffer)
struct fullstat *Buffer;
char *Path;
int Command;

int ffullstat (FileDescriptor, Command, Buffer)
struct fullstat *Buffer;
int FileDescriptor;
int Command;

int stat64 ( Path, Buffer)
const char *Path;
struct stat64 *Buffer;

int lstat64 (Path, Buffer)
const char *Path;
struct stat64 *Buffer;


int fstat64 ( FileDescriptor, Buffer)
int FileDescriptor;
struct stat64 *Buffer;

Description

The stat subroutine obtains information about the file named by the Path parameter. Read, write, or execute permission for the named file is not required, but all directories listed in the path leading to the file must be searchable. The file information, which is a subset of the stat structure, is written to the area specified by the Buffer parameter.

The lstat subroutine obtains information about a file that is a symbolic link. The lstat subroutine returns information about the link, while the stat subroutine returns information about the file referenced by the link.

The fstat subroutine obtains information about the open file referenced by the FileDescriptor parameter. The fstatx subroutine obtains information about the open file referenced by the FileDescriptor parameter, as in the fstat subroutine.

The st_mode, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime fields of the stat structure have meaningful values for all file types. The statx, stat, lstat, fstatx, fstat, fullstat, or ffullstat subroutine sets the st_nlink field to a value equal to the number of links to the file.

The statx subroutine obtains a greater set of file information than the stat subroutine. The Path parameter is processed differently, depending on the contents of the Command parameter. The Command parameter provides the ability to collect information about symbolic links (as with the lstat subroutine) as well as information about mount points and hidden directories. The statx subroutine returns the amount of information specified by the Length parameter.

The fullstat and ffullstat subroutines are interfaces maintained for backward compatibility. With the exception of some field names, the fullstat structure is identical to the stat structure.

The stat64, lstat64, and fstat64 subroutines are similar to the stat, lstat, fstat subroutines except that they return file information in a stat64 structure instead of a stat structure. The information is identical except that the st_size field is defined to be a 64-bit size. This allows stat64, lstat64, and fstat64 to return file sizes which are greater than OFF_MAX (2 gigbytes minus 1).

In the large file enabled programming environment, stat is redefined to be stat64, lstat is redefined to be lstat64 and fstat is redefined to be fstat64.

Parameters

Path
Specifies the path name identifying the file. This name is interpreted differently depending on the interface used.
FileDescriptor
Specifies the file descriptor identifying the open file.
Buffer
Specifies a pointer to the stat structure in which information is returned. The stat structure is described in the sys/stat.h file.
Length
Indicates the amount of information, in bytes, to be returned. Any value between 0 and the value returned by the STATXSIZE macro, inclusive, may be specified. The following macros may be used:
STATSIZE
Specifies the subset of the stat structure that is normally returned for a stat call.
FULLSTATSIZE
Specifies the subset of the stat (fullstat) structure that is normally returned for a fullstat call.
STATXSIZE
Specifies the complete stat structure. 0 specifies the complete stat structure, as if STATXSIZE had been specified.
 
Command
Specifies a processing option. For the statx subroutine, the Command parameter determines how to interpret the path name provided, specifically, whether to retrieve information about a symbolic link, hidden directory, or mount point. Flags can be combined by logically ORing them together. The following options are possible values:
STX_LINK
If the Command parameter specifies the STX_LINK flag and the Path parameter is a path name that refers to a symbolic link, the statx subroutine returns information about the symbolic link. If the STX_LINK flag is not specified, the statx subroutine returns information about the file to which the link refers.

If the Command parameter specifies the STX_LINK flag and the Path value refers to a symbolic link, the st_mode field of the returned stat structure indicates that the file is a symbolic link.

STX_HIDDEN
If the Command parameter specifies the STX_HIDDEN flag and the Path value is a path name that refers to a hidden directory, the statx subroutine returns information about the hidden directory. If the STX_HIDDEN flag is not specified, the statx subroutine returns information about a subdirectory of the hidden directory.

If the Command parameter specifies the STX_HIDDEN flag and Path refers to a hidden directory, the st_mode field of the returned stat structure indicates that this is a hidden directory.

STX_MOUNT
If the Command parameter specifies the STX_MOUNT flag and the Path value is the name of a file or directory that has been mounted over, the statx subroutine returns information about the mounted-over file. If the STX_MOUNT flag is not specified, the statx subroutine returns information about the mounted file or directory (the root directory of a virtual file system).

If the Command parameter specifies the STX_MOUNT flag, the FS_MOUNT bit in the st_flag field of the returned stat structure is set if, and only if, this file is mounted over.

If the Command parameter does not specify the STX_MOUNT flag, the FS_MOUNT bit in the st_flag field of the returned stat structure is set if, and only if, this file is the root directory of a virtual file system.

STX_NORMAL
If the Command parameter specifies the STX_NORMAL flag, then no special processing is performed on the Path value. This option should be used when STX_LINK, STX_HIDDEN, and STX_MOUNT flags are not desired.

For the fstatx subroutine, there are currently no special processing options. The only valid value for the Command parameter is the STX_NORMAL flag.

For the fullstat and ffullstat subroutines, the Command parameter may specify the FL_STAT flag, which is equivalent to the STX_NORMAL flag, or the FL_NOFOLLOW flag, which is equivalent to STX_LINK flag.

STX_64
If the Command parameter specifies the STX_64 flag and the file size is greater than OFF_MAX, then statx succeeds and returns the file size. Otherwise, statx fails and sets the errno to EOVERFLOW.

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The stat, lstat, statx, and fullstat subroutines are unsuccessful if one or more of the following are true:

EACCES Search permission is denied for one component of the path prefix.
ENAMETOOLONG The length of the path prefix exceeds the PATH_MAX flag value or a path name is longer than the NAME_MAX flag value while the POSIX_NO_TRUNC flag is in effect.
ENOTDIR A component of the path prefix is not a directory.
EFAULT Either the Path or the Buffer parameter points to a location outside of the allocated address space of the process.
ENOENT The file named by the Path parameter does not exist.
EOVERFLOW The size of the file is larger than can be represented in the stat structure pointed to by the Buffer parameter.

The stat, lstat, statx, and fullstat subroutines can be unsuccessful for other reasons. See "Base Operating System Error Codes for Services that Require Path-Name Resolution" for a list of additional errors.

The fstat, fstatx, and ffullstat subroutines fail if one or more of the following are true:

EBADF The FileDescriptor parameter is not a valid file descriptor.
EFAULT The Buffer parameter points to a location outside the allocated address space of the process.
EIO An input/output (I/O) error occurred while reading from the file system.

The statx and fstatx subroutines are unsuccessful if one or more of the following are true:

EINVAL The Length value is not between 0 and the value returned by the STATSIZE macro, inclusive.
EINVAL The Command parameter contains an unacceptable value.

Files

/usr/include/sys/fullstat.h Contains the fullstat structure.
/usr/include/sys/mode.h Defines values on behalf of the stat.h file.

Related Information

The chmod subroutine, chown subroutine, link subroutine, mknod subroutine, mount (vmount or mount Subroutine) subroutine, openx, open, or creat subroutine, pipe subroutine, symlink (symlink Subroutine) subroutine, vtimes subroutine.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]