Fungsi SearchPathA (processenv.h)

Mencari file tertentu dalam jalur tertentu.

Sintaksis

DWORD SearchPathA(
  [in, optional]  LPCSTR lpPath,
  [in]            LPCSTR lpFileName,
  [in, optional]  LPCSTR lpExtension,
  [in]            DWORD  nBufferLength,
  [out]           LPSTR  lpBuffer,
  [out, optional] LPSTR  *lpFilePart
);

Parameter

[in, optional] lpPath

Jalur yang akan dicari untuk file tersebut.

Jika parameter ini NULL, fungsi mencari file yang cocok menggunakan jalur pencarian sistem yang bergantung pada registri. Untuk informasi selengkapnya, lihat bagian Keterangan.

[in] lpFileName

Nama file yang akan dicari.

Secara default, nama dibatasi untuk MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan awal "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Penamaan File, Jalur, dan Namespace.

Ujung

Dimulai dengan Windows 10, Versi 1607, Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa prepending "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" Penamaan File, Jalur, dan Namespace untuk detailnya.

[in, optional] lpExtension

Ekstensi yang akan ditambahkan ke nama file saat mencari file. Karakter pertama ekstensi nama file harus berupa titik (.). Ekstensi ditambahkan hanya jika nama file yang ditentukan tidak berakhir dengan ekstensi.

Jika ekstensi nama file tidak diperlukan atau jika nama file berisi ekstensi, parameter ini dapat NULL.

[in] nBufferLength

Ukuran buffer yang menerima jalur dan nama file yang valid (termasuk karakter null yang dihentikan), dalam TCHAR.

[out] lpBuffer

Penunjuk ke buffer untuk menerima jalur dan nama file file yang ditemukan. String adalah string null-terminated.

[out, optional] lpFilePart

Penunjuk ke variabel untuk menerima alamat (dalam lpBuffer) dari komponen terakhir dari jalur dan nama file yang valid, yang merupakan alamat karakter segera mengikuti garis miring terbalik akhir (\) di jalur.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah panjangnya, dalam TCHAR, dari string yang disalin ke buffer, tidak termasuk karakter null yang mengakhiri. Jika nilai yang dikembalikan lebih besar dari nBufferLength, nilai yang dikembalikan adalah ukuran buffer yang diperlukan untuk menahan jalur, termasuk karakter null yang mengakhiri.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Jika parameter lpPath null, SearchPath mencari file yang cocok berdasarkan nilai saat ini dari nilai registri berikut:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SafeProcessSearchMode

Ketika nilai registri REG_DWORD ini diatur ke 1, SearchPath terlebih dahulu mencari folder yang ditentukan di jalur sistem, lalu mencari folder kerja saat ini. Ketika nilai registri ini diatur ke 0, komputer terlebih dahulu mencari folder kerja saat ini, lalu mencari folder yang ditentukan di jalur sistem. Nilai default sistem untuk kunci registri ini adalah 0.

Mode pencarian yang digunakan oleh fungsi SearchPath juga dapat diatur per proses dengan memanggil fungsi SetSearchPathMode .

Fungsi SearchPath tidak disarankan sebagai metode untuk menemukan file .dll jika penggunaan output yang dimaksudkan dalam panggilan ke fungsi LoadLibrary . Ini dapat mengakibatkan menemukan file .dll yang salah karena urutan pencarian fungsi SearchPath berbeda dari urutan pencarian yang digunakan oleh fungsi LoadLibrary . Jika Anda perlu menemukan dan memuat file .dll, gunakan fungsi LoadLibrary .

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

 

Nota

Header processenv.h mendefinisikan SearchPath sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Platform Target	Windows
Header	processenv.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

File Management Functions

FindFirstFile

FindNextFile

GetSystemDirectory

GetWindowsDirectory

SetSearchPathMode