[Previous]
[Contents]
[Next]

fstat()

obtain information about an open file

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
int  fstat( int filedes, struct stat *buf );

Description:

The fstat() function obtains information about an open file whose file descriptor is filedes. This information is placed in the structure located at the address indicated by buf.

The file <sys/stat.h> contains definitions for the structure stat and at least the following macros:

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 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.
Nonzero
the information wasn't successfully obtained. When an error has occurred, errno indicates the type of error detected.

Errors:

EBADF
filedes isn't a valid file descriptor.

Examples:

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

void main()
  {
    int filedes, 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 );
    }
  }

Classification:

POSIX 1003.1

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread Yes

See also:

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


[Previous]
[Contents]
[Next]