NAME

stat, fstat, lstat − Provides information about a file

SYNOPSIS

#include <sys/types.h> #include <sys/stat.h> int stat(
const char ∗path,
struct stat ∗buffer ); int lstat(
const char ∗path,
struct stat ∗buffer ); int fstat(
int filedes,
struct stat ∗buffer );

PARAMETERS

pathSpecifies the pathname identifying the file. 

filedesSpecifies the file descriptor identifying the open file. 

bufferPoints to the stat structure in which information is returned. The stat structure is described in the sys/stat.h header file. 

DESCRIPTION

The stat() function 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 pathname leading to the file must be searchable.  The file information is written to the area specified by the buffer parameter, which is a pointer to a stat structure, defined in sys/stat.h as follows:

struct  stat
{
    dev_t   st_dev;      /∗ ID of device containing a directory∗/
                         /∗   entry for this file.  File serial∗/
                         /∗   no + device ID uniquely identify ∗/
                         /∗   the file within the system ∗/
    ino_t   st_ino;      /∗ File serial number ∗/
    mode_t  st_mode;     /∗ File mode; see #define’s below ∗/
    nlink_t st_nlink;    /∗ Number of links ∗/
    uid_t   st_uid;      /∗ User ID of the file’s owner ∗/
    gid_t   st_gid;      /∗ Group ID of the file’s group ∗/
    dev_t   st_rdev;     /∗ ID of device ∗/
                         /∗   This entry is defined only for ∗/
                         /∗   character or block special files ∗/
    off_t   st_size;     /∗ File size in bytes ∗/
    time_t  st_atime;    /∗ Time of last access ∗/
    int     st_spare1;
    time_t  st_mtime;    /∗ Time of last data modification ∗/
    int     st_spare2;
    time_t  st_ctime;    /∗ Time of last file status change ∗/
    int     st_spare3;
                         /∗ Time measured in seconds since ∗/
                         /∗   00:00:00 GMT, Jan. 1, 1970 ∗/
    uint_t  st_blksize;  /∗ Size of block in file ∗/
    int    st_blocks;    /∗ blocks allocated for file ∗/
    uint_t  st_flags;    /∗ user defined flags for file ∗/
    uint_t  st_gen;      /∗ file generation number ∗/
};

The values of the mode_t information are defined in <sys/mode.h> as follows:

The fstat() function is like the stat() function except that the information obtained is about an open file referenced by the filedes parameter. 

The lstat() function is like the stat() function except in the case where the named file is a symbolic link.  In this case, the lstat() function returns information about the link, while the stat() and fstat() functions return information about the file the link references.  In the case of a symbolic link, the stat() functions set the st_size field of the stat structure to the length of the symbolic link, and sets the st_mode field to indicate the file type. 

The stat(), lstat(), and fstat() functions update any time-related fields associated with the file before writing into the stat structure. 

NOTES

AES Support Level:
Full use (stat(), fstat())

Trial use (lstat())

RETURN VALUES

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

ERRORS

If the stat() or lstat() function fails, errno may be set to one of the following values:

[EACCES]Search permission is denied for a component of the path parameter. 

[EFAULT]Either the buffer parameter or the path parameter points to a location outside of the allocated address space of the process. 

[ELOOP]Too many links were encountered in translating path. 

[ENAMETOOLONG]
The length of the path parameter exceeds PATH_MAX or a pathname component is longer than NAME_MAX. 

[ENOENT]The file named by the path parameter does not exist or is an empty string. 

[ENOTDIR]A component of the path parameter is not a directory. 

For NFS file access, if the stat() or lstat() function fails, errno may also be set to one of the following values:

[EINVAL]The file position pointer associated with the filedes parameter was negative. 

[EISDIR]Indicates either that the request was for a write access to a file but the specified filename was actually a directory, or that the function was trying to rename a directory as a file. 

[ENFILE]Indicates either that the system file table is full, or that there are too many files currently open in the system. 

[ESTALE]Indicates a stale NFS file handle.  An opened file was deleted by the server or another client; a client cannot open a file because the server has unmounted or unexported the remote directory; or the directory that contains an opened file was either unmounted or unexported by the server. 

If the fstat() function fails, errno may be set to one of the following values:

[EBADF]The filedes parameter is not a valid file descriptor. 

[EFAULT]The buffer parameter points to a location outside of the allocated address space of the process. 

RELATED INFORMATION

Functions: chmod(2), chown(2), link(2), mknod(2), mount(3), open(2), pipe(2), symlink(2), utime(2)