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;

Note: The stat64, lstat64, and fstat64 subroutines apply to Version 4.2 and later releases.

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

Note: The stat64, lstat64, and fstat64 subroutines apply to Version 4.2 and later releases.

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

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:

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" on page A-1 for a list of additional errors.

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

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

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Files

Related Information

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

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