DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

stat(S)


stat, fstat, lstat, statlstat -- returns file status

Syntax

cc . . . -lc

#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

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

See also

chmod(S), chown(S), creat(S), link(S), mknod(S), pipe(S), read(S), readlink(S), signal(S), symlink(S), time(S), unlink(S), utime(S), write(S)

Standards conformance

fstat and stat are conformant with:

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.


© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003