[Previous]
[Contents]
[Next]

stat()

get information about a file or directory

Synopsis:

#include <sys/stat.h>
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.


Note: This function follows symbolic links and gives you information about the resulting file or directory. If you want information about the link itself, use lstat() instead.

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_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 nonzero 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 the Header Files 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.
-1
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.

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:

POSIX 1003.1
Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

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


[Previous]
[Contents]
[Next]