_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32

The latest version of this topic can be found at _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, in the case of 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.

st_atime
Time of the last file access.

st_ctime
Time of the creation of the file.

st_dev
If a device, fd; otherwise 0.

st_mode
Bit mask for file-mode information. The _S_IFCHR bit is set if fd refers to a device. The _S_IFREG bit is set if fd refers to an ordinary file. The read/write bits are set according to the file's permission mode. _S_IFCHR and other constants are defined in SYS\Stat.h.

st_mtime
Time of the last modification of the file.

st_nlink
Always 1 on non-NTFS file systems.

st_rdev
If a device, fd; otherwise 0.

st_size
Size of the file in bytes.

If fd refers to a device, the st_atime, st_ctime, st_mtime, and st_size fields are not 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. Midnight, January 1, 1970, is the lower bound of the date range for all these functions.

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.

_fstat is equivalent to _fstat64i32, and struct``_stat contains a 64-bit time. This is true unless _USE_32BIT_TIME_T is defined, in which case the old behavior is in effect; _fstat uses a 32-bit time, and struct``_stat contains a 32-bit time. The same is true for _fstati64.

Time Type and File Length Type Variations of _stat

Requirements

For more compatibility information, see Compatibility in the Introduction.

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  

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

See Also

File Handling
_access, _waccess
_chmod, _wchmod
_filelength, _filelengthi64
_stat, _wstat Functions