stat, _stat

get information about a file or directory

Synopsis:

#include <sys/stat.h>
int stat( const char *path, struct stat *buf );
int _stat( const char *path, struct stat *buf );

Description:

The stat() function obtains information about the file or directory referenced in path. This information is placed in the structure located at the address indicated by buf.

The _stat() function is identical to stat(). Use _stat() for ANSI naming conventions.

The file sys/stat.h contains definitions for the structure stat.

At least the following macros are defined in the sys/stat.h header file:

S_ISBLK(m)

Test for block special file.

S_ISCHR(m)

Test for character special file.

S_ISDIR(m)

Test for directory file.

S_ISFIFO(m)

Test for FIFO.

S_ISLNK(m)

Test for symbolic link.

S_ISREG(m)

Test for regular file.

The value m supplied to the macros is the value of the st_mode field of a stat structure. The macro evaluates to a non-zero value if the test is true, and zero if the test is false.

The access permissions for the file or directory are specified as a combination of bits in the st_mode field of a stat structure. These bits are defined in the sys/stat.h header file, and are described in the section on this file in “Header Files in /usr/include/sys” of the C Library Overview chapter. The following bits are also encoded in the st_mode field:

S_ISUID

Set user ID on execution. The process's effective user ID is set to that of the owner of the file when the file is run as a program. On a regular file, this bit should be cleared on any write.

S_ISGID

Set group ID on execution. Set effective group ID on the process to the file's group when the file is run as a program. On a regular file, this bit should be cleared on any write.

Returns:

0

the information was successfully obtained.

non-zero

the information wasn't successfully obtained.

Errors:

EACCES

Search permission is denied for a component of path.

EIO

A physical error occurred on the block device.

ENAMETOOLONG

The argument path exceeds PATH_MAX in length, or a pathname component is longer than NAME_MAX. These manifests are defined in the limits.h header file.

ENOENT

The named file doesn't exist, or path is an empty string.

ENOTDIR

A component of path isn't a directory.

See also:

errno, fstat(), fsys_stat(), fsys_fstat(), lstat()

Examples:

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

void main()
  {
    struct stat buf;

    if( stat( "file", &buf ) != -1 ) {
      printf( "File size = %d\n", buf.st_size );
    }
  }

Classification:

_stat() conforms to ANSI naming conventions.

Systems:

stat()

All (except Netware, DOS/PM)

_stat()

All (except DOS/PM)