_findfirst, , _findfirst32i64_findfirst32, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, , _wfindfirst64, , _wfindfirst64i32_wfindfirsti64

Berikan informasi tentang instans pertama nama file yang cocok dengan file yang ditentukan dalam filespec argumen.

Sintaks

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
);

Parameter

filespec
Spesifikasi file target (dapat menyertakan karakter kartubebas).

fileinfo
Buffer informasi file. Untuk informasi selengkapnya tentang fileinfo struktur, lihat Keterangan dalam fungsi pencarian Nama File dan lihat Pemetaan jenis data. Struktur didefinisikan dalam file header yang sama dengan fungsi yang menggunakannya sebagai parameter.

Nilai hasil

Jika berhasil, _findfirst mengembalikan handel pencarian unik yang mengidentifikasi file atau grup file yang cocok dengan filespec spesifikasi, yang dapat digunakan dalam panggilan berikutnya ke _findnext atau ke _findclose. Jika tidak, _findfirst mengembalikan -1 dan mengatur errno ke salah satu nilai berikut.

nilai errno	Kondisi
EINVAL	Parameter tidak valid: filespec atau fileinfo adalah NULL. Atau, sistem operasi mengembalikan kesalahan tak terduga.
ENOENT	Spesifikasi file yang tidak dapat dicocokkan.
ENOMEM	Memori tidak cukup.
EINVAL	Spesifikasi nama file tidak valid atau nama file yang diberikan lebih besar dari MAX_PATH.

Untuk informasi selengkapnya tentang kode pengembalian ini dan lainnya, lihat errno, , _doserrno_sys_errlist, dan _sys_nerr.

Jika parameter yang tidak valid diteruskan, fungsi-fungsi ini memanggil handler parameter yang tidak valid, seperti yang dijelaskan dalam Validasi parameter.

Keterangan

Anda harus memanggil _findclose setelah selesai dengan _findfirst fungsi atau _findnext (atau varian apa pun) yang menyediakan panggilan untuk _findfirst berhasil. _findclose membebaskan sumber daya yang digunakan oleh fungsi-fungsi ini dalam aplikasi Anda. Memanggil _findclose pada handel yang tidak valid mengembalikan -1 dan mengatur errno ke EINVAL.

Variasi fungsi-fungsi ini yang memiliki w awalan adalah versi karakter lebar; jika tidak, fungsi tersebut identik dengan fungsi byte tunggal yang sesuai.

Variasi fungsi ini mendukung jenis waktu 32-bit atau 64-bit dan ukuran file 32-bit atau 64-bit. Akhiran numerik pertama (32 atau 64) menunjukkan ukuran jenis waktu; akhiran kedua adalah i32 atau i64, dan menunjukkan apakah ukuran file diwakili sebagai bilangan bulat 32-bit atau 64-bit. Untuk informasi tentang versi mana yang mendukung jenis waktu dan ukuran file 32-bit dan 64-bit, lihat tabel berikut ini. Akhiran i32 atau i64 dihilangkan jika sama dengan ukuran jenis waktu, jadi _findfirst64 juga mendukung panjang file 64-bit dan _findfirst32 hanya mendukung panjang file 32-bit.

Fungsi-fungsi ini menggunakan berbagai bentuk _finddata_t struktur untuk fileinfo parameter . Untuk informasi selengkapnya tentang struktur, lihat Fungsi pencarian nama file.

Variasi yang menggunakan jenis waktu 64-bit memungkinkan tanggal pembuatan file dinyatakan hingga 23:59:59, 31 Desember 3000, UTC. Yang menggunakan jenis waktu 32-bit hanya mewakili tanggal hingga 23:59:59 18 Januari 2038, UTC. Tengah malam, 1 Januari 1970, adalah batas bawah rentang tanggal untuk semua fungsi ini.

Kecuali Anda memiliki alasan khusus untuk menggunakan versi yang menentukan ukuran waktu secara eksplisit, gunakan _findfirst atau _wfindfirst atau, jika Anda perlu mendukung ukuran file yang lebih besar dari 3 GB, gunakan _findfirsti64 atau _wfindfirsti64. Semua fungsi ini menggunakan jenis waktu 64-bit. Dalam versi sebelumnya, fungsi-fungsi ini menggunakan jenis waktu 32-bit. Jika perubahan ini adalah perubahan yang melanggar untuk aplikasi, Anda mungkin menentukan _USE_32BIT_TIME_T untuk kembali ke perilaku lama. Jika _USE_32BIT_TIME_T didefinisikan, _findfirst, _findfirsti64, dan versi Unicode yang sesuai menggunakan waktu 32-bit.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Jenis Waktu dan Variasi Tipe Panjang File _findfirst

Fungsi	_USE_32BIT_TIME_T Didefinisikan?	Jenis waktu	Jenis panjang file
_findfirst, _wfindfirst	Tidak ditentukan	64-bit	32-bit
_findfirst, _wfindfirst	Didefinisikan	32-bit	32-bit
_findfirst32, _wfindfirst32	Tidak terpengaruh oleh definisi makro	32-bit	32-bit
_findfirst64, _wfindfirst64	Tidak terpengaruh oleh definisi makro	64-bit	64-bit
_findfirsti64, _wfindfirsti64	Tidak ditentukan	64-bit	64-bit
_findfirsti64, _wfindfirsti64	Didefinisikan	32-bit	64-bit
_findfirst32i64, _wfindfirst32i64	Tidak terpengaruh oleh definisi makro	32-bit	64-bit
_findfirst64i32, _wfindfirst64i32	Tidak terpengaruh oleh definisi makro	64-bit	32-bit

Pemetaan rutin teks generik

Tchar.h Rutin	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

Persyaratan

Fungsi	Header yang diperlukan
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> atau <wchar.h>
_wfindfirst32	<io.h> atau <wchar.h>
_wfindfirst64	<io.h> atau <wchar.h>
_wfindfirsti64	<io.h> atau <wchar.h>
_wfindfirst32i64	<io.h> atau <wchar.h>
_wfindfirst64i32	<io.h> atau <wchar.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Lihat juga

Panggilan sistem
Fungsi pencarian nama file