_stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32, _wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32

Obtenha informações de status em um arquivo.

Sintaxe

int _stat(
   const char *path,
   struct _stat *buffer
);
int _stat32(
   const char *path,
   struct __stat32 *buffer
);
int _stat64(
   const char *path,
   struct __stat64 *buffer
);
int _stati64(
   const char *path,
   struct _stati64 *buffer
);
int _stat32i64(
   const char *path,
   struct _stat32i64 *buffer
);
int _stat64i32(
   const char *path,
   struct _stat64i32 *buffer
);
int _wstat(
   const wchar_t *path,
   struct _stat *buffer
);
int _wstat32(
   const wchar_t *path,
   struct __stat32 *buffer
);
int _wstat64(
   const wchar_t *path,
   struct __stat64 *buffer
);
int _wstati64(
   const wchar_t *path,
   struct _stati64 *buffer
);
int _wstat32i64(
   const wchar_t *path,
   struct _stat32i64 *buffer
);
int _wstat64i32(
   const wchar_t *path,
   struct _stat64i32 *buffer
);

Parâmetros

path
Ponteiro para uma cadeia de caracteres contendo o caminho do arquivo ou diretório existente.

buffer
Ponteiro para estrutura que armazena os resultados.

Retornar valor

Cada uma dessas funções retornará 0 se as informações de status do arquivo forem obtidas. Um valor de retorno de -1 indica um erro, caso errno em que é definido como ENOENT, indicando que o nome do arquivo ou caminho não pôde ser encontrado. Um valor retornado EINVAL indica um parâmetro inválido; errno também é definido como EINVAL nesse caso.

Para obter mais informações sobre códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

O carimbo de data em um arquivo pode ser representado se for depois da meia-noite, 1º de janeiro de 1970, e antes das 23:59:59, 31 de dezembro de 3000, UTC, a menos que você use _stat32 ou , ou _wstat32tenha definido _USE_32BIT_TIME_T, caso em que a data pode ser representada apenas até 23:59:59 18 de janeiro de 2038, UTC.

Comentários

A função _stat obtém informações sobre o arquivo ou o diretório especificados por path e as armazena na estrutura apontada por buffer. _stat manipula automaticamente argumentos de cadeia de caracteres multibyte conforme apropriado, reconhecendo sequências de caracteres multibyte de acordo com a página de código multibyte que está sendo usada no momento.

A função _wstat é uma versão de caractere largo da função _stat; o argumento path para _wstat é uma cadeia de caracteres larga. _wstat e _stat têm comportamento idêntico, exceto pelo fato de que _wstat não manipula cadeias de caracteres multibyte.

As variações dessas funções oferecem suporte a tipos de tempo de 32 bits ou 64 bits e comprimentos de arquivo de 32 bits ou 64 bits. O primeiro sufixo numérico (32 ou 64) indica o tamanho do tipo de hora usado; o segundo sufixo é i32 ou i64, que indica se o tamanho do arquivo é representado como um inteiro de 32 ou de 64 bits.

_staté equivalente a , e contém um tempo de 64 bits, a _stat64i32menos que _USE_32BIT_TIME_T seja definido, caso em que o comportamento antigo está em vigor, _stat usa um tempo de 32 bits e struct _statstruct _stat contém um tempo de 32 bits. O mesmo vale para _stati64.

Observação

_wstat não funciona com links simbólicos do Windows Vista. Nesses casos, _wstat sempre relatará um tamanho do arquivo de 0. _stat funciona corretamente com links simbólicos. A _statfamília de funções usa CreateFile no Visual Studio 2015, em vez de FindFirstFile como no Visual Studio 2013 e versões anteriores. Isso significa que em um caminho que _stat termina com uma barra será bem-sucedido se o caminho se referir a um diretório, ao contrário de antes, quando a função seria erro com errno set como ENOENT.

Essa função valida seus parâmetros. Se um path ou buffer for NULL, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Variações de tipo de tempo e tipo de comprimento de arquivo de _stat

Funções	_USE_32BIT_TIME_T definido	Tipo de hora	Tipo de tamanho de arquivo
_stat, _wstat	Não definido	64 bits	32 bits
_stat, _wstat	Definido	32 bits	32 bits
_stat32, _wstat32	Não afetado pela definição de macro	32 bits	32 bits
_stat64, _wstat64	Não afetado pela definição de macro	64 bits	64 bits
_stati64, _wstati64	Não definido	64 bits	64 bits
_stati64, _wstati64	Definido	32 bits	64 bits
_stat32i64, _wstat32i64	Não afetado pela definição de macro	32 bits	64 bits
_stat64i32, _wstat64i32	Não afetado pela definição de macro	64 bits	32 bits

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tstat	_stat	_stat	_wstat
_tstat64	_stat64	_stat64	_wstat64
_tstati64	_stati64	_stati64	_wstati64
_tstat32i64	_stat32i64	_stat32i64	_wstat32i64
_tstat64i32	_stat64i32	_stat64i32	_wstat64i32

A estrutura _stat, definida em SYS\STAT.H, contém os campos a seguir.

Campo	Descrição
st_gid	Identificador numérico do grupo que possui o arquivo (específico do UNIX). Esse campo sempre será zero em sistemas Windows. Um arquivo redirecionado é classificado como um arquivo do Windows.
st_atime	Hora do último acesso ao arquivo. Válido em unidades de disco formatadas como NTFS, mas não naquelas formatadas como FAT.
st_ctime	Hora de criação do arquivo. Válido em unidades de disco formatadas como NTFS, mas não naquelas formatadas como FAT.
st_dev	Número da unidade do disco que contém o arquivo (o mesmo que st_rdev).
st_ino	Número do nó de informações (o inode) para o arquivo (específico do UNIX). Em sistemas de arquivos UNIX, o inode descreve a data do arquivo e carimbos de data/hora, permissões e conteúdo. Quando arquivos são vinculados fisicamente uns aos outros, eles compartilham o mesmo inode. inode e, portanto, st_ino, não tem nenhum significado nos sistemas de arquivos FAT, HPFS ou NTFS.
st_mode	Máscara de bits para informações sobre o modo de arquivo. O _S_IFDIR bit é definido se path especifica um diretório; o bit _S_IFREG é definido se path especifica um arquivo comum ou um dispositivo. Bits de leitura/gravação do usuário são definidos de acordo com o modo de permissão do arquivo; bits de execução do usuário são definidos de acordo com a extensão de nome de arquivo.
st_mtime	Hora da última modificação do arquivo.
st_nlink	Sempre 1 em sistemas de arquivos diferentes de NTFS.
st_rdev	Número da unidade do disco que contém o arquivo (o mesmo que st_dev).
st_size	Tamanho do arquivo em bytes. um inteiro de 64 bits para variações com o sufixo i64.
st_uid	Identificador numérico do usuário que possui o arquivo (específico do UNIX). Esse campo sempre será zero em sistemas Windows. Um arquivo redirecionado é classificado como um arquivo do Windows.

Se path refere-se a um dispositivo, o st_size, campos de hora diversos, st_dev e campos st_rdev na estrutura _stat não têm importância. Como STAT.H usa o tipo _dev_t que é definido em TYPES.H, você precisa incluir TYPES.H antes de STAT.H no código.

Requisitos

Rotina	Cabeçalho necessário	Cabeçalhos opcionais
_stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32	<sys/types.h> seguido por <sys/stat.h>	<errno.h>
_wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32	<sys/types.h> seguido por <sys/stat.h> ou <wchar.h>	<errno.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_stat.c
// This program uses the _stat function to
// report information about the file named crt_stat.c.

#include <time.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <errno.h>

int main( void )
{
   struct _stat buf;
   int result;
   char timebuf[26];
   char* filename = "crt_stat.c";
   errno_t err;

   // Get data associated with "crt_stat.c":
   result = _stat( filename, &buf );

   // Check if statistics are valid:
   if( result != 0 )
   {
      perror( "Problem getting information" );
      switch (errno)
      {
         case ENOENT:
           printf("File %s not found.\n", filename);
           break;
         case EINVAL:
           printf("Invalid parameter to _stat.\n");
           break;
         default:
           /* Should never be reached. */
           printf("Unexpected error in _stat.\n");
      }
   }
   else
   {
      // Output some of the statistics:
      printf( "File size     : %ld\n", buf.st_size );
      printf( "Drive         : %c:\n", buf.st_dev + 'A' );
      err = ctime_s(timebuf, 26, &buf.st_mtime);
      if (err)
      {
         printf("Invalid arguments to ctime_s.");
         exit(1);
      }
      printf( "Time modified : %s", timebuf );
   }
}

File size     : 732
Drive         : C:
Time modified : Thu Feb 07 14:39:36 2002

Confira também

Manipulação de arquivos
_access, _waccess
_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32
_getmbcp
_setmbcp