stat(S)

Syntax

#include  <sys/types.h>
#include  <sys/stat.h>

int stat (path, buf)
char *path;
struct stat *buf;

int fstat (fildes, buf)
int fildes;
struct stat *buf;

int lstat (path, buf)
char *path;
struct stat *buf;

int statlstat (path, buf)
char *path;
struct stat *buf;

S_ISBLK (fmode)

S_ISCHR (fmode)

S_ISDIR (fmode)

S_ISFIFO (fmode)

S_ISNAM (fmode)

S_ISREG (fmode)

Description

The stat system call obtains information about the named file. Both the stat and fstat functions update any time-related fields before writing into the stat structure.

fstat obtains information about an open file known by the file descriptor fildes, obtained from a successful open, creat, dup, fcntl, or pipe system call.

lstat obtains information about a symbolic link. Use the macro S_ISLNK to determine if the file is a symbolic link.

Calls to lstat or symlink made on a kernel on which these calls are not supported, such as SCO UNIX System V Version 2.0, produce the signal SIGSYS. Programs can be made to operate correctly on kernels that do and do not support these routines by first calling lstat(S) and then calling stat(S) if SIGSYS is produced by the first call.

path points to a path name naming a file. Read, write, or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. An implementation that provides extended security controls may, under implementation-defined conditions, cause the stat function to fail. In particular, the system may deny the existence of the file specified by path.

The lstat system call is supported by SCO UNIX System V Version 4.0, but not by earlier versions of SCO UNIX systems. A SIGSYS signal is sent to a program attempting an lstat system call on earlier versions, which typically results in a core dump. If you are developing a program to use lstat, and that program is also required to run on systems which do not support lstat, then you should use statlstat in place of lstat. On its first call to lstat, statlstat uses signal(S) to catch SIGSYS without core dumping, and uses stat instead and thereafter, if the system does not support lstat.

The S_IS macros provide POSIX file testing capabilities. The fmode argument is the file mode. If a test is correct, a nonzero value is returned; otherwise, a value of zero is returned. The purpose of the update any time-related fieeds before writing into the macros is:

Macro	Purpose
S_ISBLK	determine if file is a block special file
S_ISCHR	determine if file is a character special file
S_ISDIR	determine if file is a directory
S_ISFIFO	determine if file is a first-in, first-out (FIFO)
S_ISNAM	determine if file is a special named file
S_ISREG	determine if file is a regular file

 +---------+---------------------------------------------------+--------------+
 |Macro    | Purpose                                           |              |
 +---------+---------------------------------------------------+--------------+
 |S_ISBLK  | determine if file is a block special file         |              |
 +---------+---------------------------------------------------+--------------+
 |S_ISCHR  | determine if file is a character special file     |              |
 +---------+---------------------------------------------------+--------------+
 |S_ISDIR  | determine if file is a directory                  |              |
 +---------+---------------------------------------------------+--------------+
 |S_ISFIFO | determine if file is a first-in, first-out (FIFO) |              |
 +---------+---------------------------------------------------+--------------+
 |S_ISNAM  | determine if file is a special named file         |              |
 +---------+---------------------------------------------------+--------------+
 |S_ISREG  | determine if file is a regular file               |              |
 +---------+---------------------------------------------------+--------------+

buf is a pointer to a stat structure into which information is placed concerning the file.

The contents of the structure pointed to by buf include the following members:

   dev_t st_dev;           /* ID of device containing */
                           /* a directory entry for this file */
   ino_t   st_ino;         /* Inode number */
   mode_t  st_mode;        /* File mode (see mknod (S)) */
   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 special or */
                           /* block special files */
   off_t   st_size;        /* File size in bytes */
   time_t  st_atime;       /* Time of last access */
   time_t  st_mtime;       /* Time of last data modification */
   time_t  st_ctime;       /* Time of last file status change */
                           /* Times measured in seconds since */
   			/* 1970-01-01 00:00 UTC */

st_mode

The mode of the file as described in the mknod(S) system call.

st_ino

This field uniquely identifies the file in a given file system. The pair st_ino and st_dev uniquely identifies regular files.

st_dev

This field uniquely identifies the file system that contains the file. Its value may be used as input to the ustat(S) system call to determine more information about this file system. No other meaning is associated with this value.

st_rdev

This field should be used only by administrative commands. It is valid only for block special or character special files and only has meaning on the system where the file was configured.

st_nlink

This field should be used only by administrative commands.

st_uid

The user ID of the file's owner.

st_gid

The group ID of the file's group.

st_size

For regular files, this is the address of the end of the file. For pipes or fifos, this is the count of the data currently in the file. For block special or character special, this is not defined.

st_atime

Time when file data was last accessed. Changed by the following system calls: creat(S), mknod(S), pipe(S), utime(S), and read(S).

st_mtime

Time when data was last modified. Changed by the following system calls: creat(S), link(S), mknod(S), pipe(S), unlink(S), utime(S), and write(S).

st_ctime

Time when file status was last changed. Changed by the following system calls: chmod(S), chown(S), creat(S), link(S), mknod(S), pipe(S), unlink(S), utime(S), and write(S).

The stat system call fails if one or more of the following is true:

[EACCES]

Search permission is denied for a component of the path prefix.

[ENAMETOOLONG]

The length of the path argument exceeds [PATH_MAX] or a pathname component is longer than [NAME_MAX] while [_POSIX_NO_TRUNC] is in effect.

[ENOENT]

The named file does not exist.

[ENOTDIR]

A component of the path prefix is not a directory.

fstat fails if:

[EBADF]

fildes is not a valid open file descriptor.

Diagnostics

See also

Standards conformance

X/Open Portability Guide, Issue 3, 1989 ;
Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ; and NIST FIPS 151-1 .

lstat and statlstat are not part of any currently supported standard; they are an extension of AT&T System V developed by the Santa Cruz Operation and maintained by The SCO Group.