fstat(), fstat64()

Get file information

Synopsis:

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

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

int fstat64( int filedes, 
             struct stat64* buf );

Library:

libc

Description:

The fstat() and fstat64() functions get information from the file specified by filedes and stores it in the structure pointed to by buf.

The file <sys/stat.h> contains definitions for struct stat, as well as following macros:

S_ISBLK(m)

Test for block special file.

S_ISCHR(m)

Test for character special file.

S_ISDIR(m)

Test for directory.

S_ISFIFO(m)

Test for FIFO.

S_ISLNK(m)

Test for symbolic link.

S_ISREG(m)

Test for regular file.

S_TYPEISMQ(buf)

Test for message queue.

S_TYPEISSEM(buf)

Test for semaphore.

S_TYPEISSHM(buf)

Test for shared memory object.

The m supplied to the macros is the value of st_mode in a stat structure. The value buf is a pointer to a stat structure. The macros evaluate to nonzero if the test is true, and zero if the test is false.

Access permissions are specified as a combination of bits in the st_mode field of the stat structure. These bits are defined in <sys/stat.h>.

The st_mode field also encodes the following bits:

S_ISUID

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

S_ISGID

Set group ID on execution. Set effective group ID (EGID) on the process to the file's group when the file is run as a program. On a regular file, this bit bit may be cleared for security reasons on any write.

Returns:

Zero for success, or nonzero if an error occurs (errno is set).

Errors:

EBADF

The filedes argument isn't a valid file descriptor.

ENOSYS

The fstat() function isn't implemented for the filesystem specified by filedes.

Examples:

#include <stdio.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdlib.h>

int main( void )
{
    int filedes;
    int rc;
    struct stat buf;

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

        close( filedes );
        
        return EXIT_SUCCESS;
    }

    return EXIT_FAILURE;
}

Classification:

fstat() is POSIX 1003.1; fstat64() is for large-file support

See also:

creat(), dup(), dup2(), errno, fcntl(), lstat(), open(), pipe(), sopen(), stat()