_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32

Gets information about an open file.

Syntax

int _fstat(
   int fd,
   struct _stat *buffer
);
int _fstat32(
   int fd,
   struct _stat32 *buffer
);
int _fstat64(
   int fd,
   struct _stat64 *buffer
);
int _fstati64(
   int fd,
   struct _stati64 *buffer
);
int _fstat32i64(
   int fd,
   struct _stat32i64 *buffer
);
int _fstat64i32(
   int fd,
   struct _stat64i32 *buffer
);

Parameters

fd
File descriptor of the open file.

buffer
Pointer to the structure to store results.

Return value

Returns 0 if the file-status information is obtained. A return value of -1 indicates an error. If the file descriptor is invalid or buffer is NULL, the invalid parameter handler is invoked, as described in Parameter validation. If execution is allowed to continue, errno is set to EBADF for an invalid file descriptor, or to EINVAL if buffer is NULL.

Remarks

The _fstat function obtains information about the open file associated with fd and stores it in the structure pointed to by buffer. The _stat structure, defined in SYS\Stat.h, contains the following fields.

If fd refers to a device, the st_atime, st_ctime, st_mtime, and st_size fields aren't meaningful.

Because Stat.h uses the _dev_t type, which is defined in Types.h, you must include Types.h before Stat.h in your code.

_fstat64, which uses the _stat64 structure, allows file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas the other functions only represent dates through 23:59:59 January 18, 2038, UTC. The lower bound of the date range for all these functions is Midnight, January 1, 1970.

Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file lengths. The first numerical suffix (32 or 64) indicates the size of the time type used; the second suffix is either i32 or i64, indicating whether the file size is represented as a 32-bit or 64-bit integer.

Unless _USE_32BIT_TIME_T is defined, _fstat is equivalent to _fstat64i32, and _stat contains a 64-bit time. When _USE_32BIT_TIME_T is defined, _fstat uses a 32-bit time, and _stat contains a 32-bit time. The same is true for _fstati64.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Time type and file length type variations of _stat

Requirements

For more compatibility information, see Compatibility.

Example

// crt_fstat.c
// This program uses _fstat to report
// the size of a file named F_STAT.OUT.

#include <io.h>
#include <fcntl.h>
#include <time.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <share.h>

int main( void )
{
   struct _stat buf;
   int fd, result;
   char buffer[] = "A line to output";
   char timebuf[26];
   errno_t err;

   _sopen_s( &fd,
             "f_stat.out",
             _O_CREAT | _O_WRONLY | _O_TRUNC,
             _SH_DENYNO,
             _S_IREAD | _S_IWRITE );
   if( fd != -1 )
      _write( fd, buffer, strlen( buffer ) );

   // Get data associated with "fd":
   result = _fstat( fd, &buf );

   // Check if statistics are valid:
   if( result != 0 )
   {
      if (errno == EBADF)
        printf( "Bad file descriptor.\n" );
      else if (errno == EINVAL)
        printf( "Invalid argument to _fstat.\n" );
   }
   else
   {
      printf( "File size     : %ld\n", buf.st_size );
      err = ctime_s(timebuf, 26, &buf.st_mtime);
      if (err)
      {
         printf("Invalid argument to ctime_s.");
         exit(1);
      }
      printf( "Time modified : %s", timebuf );
   }
   _close( fd );
}

File size     : 16
Time modified : Wed May 07 15:25:11 2003

See also

File handling
_access, _waccess
_chmod, _wchmod
_filelength, _filelengthi64
_stat, _wstat functions