_findfirst, _findfirst32, , _findfirst64_findfirst64i32, _findfirsti64, _wfindfirst_wfindfirst32i64_wfindfirst32, , _wfindfirst64i32_wfindfirst64_findfirst32i64_wfindfirsti64

Informazioni sulla prima istanza di un nome file che corrisponde al file specificato nell'argomento filespec.

Sintassi

intptr_t _findfirst(
   const char *filespec,
   struct _finddata_t *fileinfo
);
intptr_t _findfirst32(
   const char *filespec,
   struct _finddata32_t *fileinfo
);
intptr_t _findfirst64(
   const char *filespec,
   struct _finddata64_t *fileinfo
);
intptr_t _findfirsti64(
   const char *filespec,
   struct _finddatai64_t *fileinfo
);
intptr_t _findfirst32i64(
   const char *filespec,
   struct _finddata32i64_t *fileinfo
);
intptr_t _findfirst64i32(
   const char *filespec,
   struct _finddata64i32_t *fileinfo
);
intptr_t _wfindfirst(
   const wchar_t *filespec,
   struct _wfinddata_t *fileinfo
);
intptr_t _wfindfirst32(
   const wchar_t *filespec,
   struct _wfinddata32_t *fileinfo
);
intptr_t _wfindfirst64(
   const wchar_t *filespec,
   struct _wfinddata64_t *fileinfo
);
intptr_t _wfindfirsti64(
   const wchar_t *filespec,
   struct _wfinddatai64_t *fileinfo
);
intptr_t _wfindfirst32i64(
   const wchar_t *filespec,
   struct _wfinddata32i64_t *fileinfo
);
intptr_t _wfindfirst64i32(
   const wchar_t *filespec,
   struct _wfinddata64i32_t *fileinfo
);

Parametri

filespec
Specifica del file di destinazione. Può includere caratteri jolly.

fileinfo
Buffer delle informazioni del file. Per altre informazioni sugli fileinfo struct, vedere la sezione Osservazioni nelle funzioni di ricerca filename e vedere Mapping dei tipi di dati. Gli struct vengono definiti nello stesso file di intestazione della funzione che li usa come parametro.

Valore restituito

In caso di esito positivo, _findfirst restituisce un handle di ricerca univoco che identifica il file o il gruppo di file che corrispondono filespec alla specifica, che può essere usato in una chiamata successiva a _findnext o a _findclose. In caso contrario, _findfirst restituisce -1 e imposta errno su uno dei valori seguenti.

Valore errno	Condizione
EINVAL	Parametro non valido: filespec o fileinfo era NULL oppure il sistema operativo ha restituito un errore imprevisto.
ENOENT	Specifica del file non corrispondente.
ENOMEM	Memoria insufficiente.
EINVAL	Specifica del nome file non valida o nome file specificato maggiore di MAX_PATH.

Per altre informazioni su questi e altri codici restituiti, vedere errno, _doserrno, _sys_errliste _sys_nerr.

Se viene passato un parametro non valido, queste funzioni richiamano il gestore di parametri non validi, come descritto in Convalida dei parametri.

Osservazioni:

È necessario chiamare _findclose dopo aver completato l'operazione con la _findfirst funzione o _findnext (o qualsiasi variante) a condizione che la chiamata abbia _findfirst avuto esito positivo. _findclose libera le risorse usate da queste funzioni nell'applicazione. La chiamata _findclose a su un handle non valido restituisce -1 e imposta errno su EINVAL.

Le varianti di queste funzioni con w prefisso sono versioni a caratteri wide; in caso contrario, sono identiche alle funzioni a byte singolo corrispondenti.

Le varianti di queste funzioni supportano tipi time a 32 o 64 bit e dimensioni di file a 32 o a 64 bit. Il primo suffisso numerico (32 o 64) indica le dimensioni del tipo time usato. Il secondo suffisso, che può essere i32 o i64, indica se le dimensioni del file sono rappresentate come intero a 32 bit o 64 bit. Per informazioni su quali versioni supportano tipi time e dimensioni dei file a 32 bit e 64 bit, vedere la tabella seguente. Il i32 suffisso o i64 viene omesso se è uguale alla dimensione del tipo di tempo, quindi _findfirst64 supporta anche lunghezze di file a 64 bit e _findfirst32 supporta solo lunghezze di file a 32 bit.

Queste funzioni usano diverse forme della struttura _finddata_t per il parametro fileinfo. Per altre informazioni sulla struttura, vedere Funzioni di ricerca nome file.

Le varianti che usano un tipo time a 64 bit consentono di esprimere le date di creazione di file fino alle 23.59.59 del 31 dicembre 3000 UTC. Quelli che usano tipi di ora a 32 bit rappresentano le date solo alle 23.59.59 del 18 gennaio 2038, UTC. La mezzanotte del 1 gennaio 1970 è il limite inferiore dell'intervallo di date per tutte queste funzioni.

A meno che non ci sia un motivo preciso per usare le versioni che specificano la dimensione time in modo esplicito, usare _findfirst o _wfindfirst oppure, se è necessario supportare dimensioni superiori a 3 GB, usare _findfirsti64 o _wfindfirsti64. Tutte queste funzioni usano il tipo time a 64 bit. Nelle versioni precedenti queste funzioni usavano un tipo time a 32 bit. Se questa modifica è una modifica che causa un'interruzione per un'applicazione, è possibile definire _USE_32BIT_TIME_T di ripristinare il comportamento precedente. Se è definito _USE_32BIT_TIME_T, _findfirst, _findfirsti64 e le corrispondenti versioni Unicode usano un tipo time a 32 bit.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Varianti di _findfirst per il tipo time e di lunghezza dei file

Funzioni	_USE_32BIT_TIME_T definito?	Tipo Time	Tipo lunghezza file
_findfirst, _wfindfirst	Non definito	64 bit	32 bit
_findfirst, _wfindfirst	Definito	32 bit	32 bit
_findfirst32, _wfindfirst32	Non interessato dalla definizione macro	32 bit	32 bit
_findfirst64, _wfindfirst64	Non interessato dalla definizione macro	64 bit	64 bit
_findfirsti64, _wfindfirsti64	Non definito	64 bit	64 bit
_findfirsti64, _wfindfirsti64	Definito	32 bit	64 bit
_findfirst32i64, _wfindfirst32i64	Non interessato dalla definizione macro	32 bit	64 bit
_findfirst64i32, _wfindfirst64i32	Non interessato dalla definizione macro	64 bit	32 bit

Mapping di routine di testo generico

Tchar.h routine	_UNICODE e _MBCS non definito	_MBCS definito	_UNICODE definito
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

Requisiti

Funzione	Intestazione obbligatoria
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> oppure <wchar.h>
_wfindfirst32	<io.h> oppure <wchar.h>
_wfindfirst64	<io.h> oppure <wchar.h>
_wfindfirsti64	<io.h> oppure <wchar.h>
_wfindfirst32i64	<io.h> oppure <wchar.h>
_wfindfirst64i32	<io.h> oppure <wchar.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Vedi anche

Chiamate di sistema
Funzioni di ricerca di nomi file