fstat(), fstat64()

Get file information, given a file description

Synopsis:

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

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

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

Arguments:

filedes: The descriptor of the file that you want to get information about.
buf: A pointer to a buffer where the function can store the information about the file.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

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 arguments to the macros are:

m: The value of st_mode in a stat structure.
buf: 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>. For more information, see “Access permissions” in the documentation for stat().

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:

0: Success.
-1: An error occurred (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.
EOVERFLOW: The file size in bytes or the number of blocks allocated to the file or the file serial number can't be represented correctly in the structure pointed to by buf.

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 Large-file support

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes