Fungsi IoCreateFile (wdm.h)

Artikel
08/08/2023

Rutinitas IoCreateFile menyebabkan file atau direktori baru dibuat, atau membuka file, perangkat, direktori, atau volume yang ada, memberi pemanggil handel untuk objek file.

Sintaks

NTSTATUS IoCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

Parameter

[out] FileHandle

Penunjuk ke variabel yang menerima handel file jika panggilan berhasil. Driver harus menutup handel dengan ZwClose setelah handel tidak lagi digunakan.

[in] DesiredAccess

Bitmask bendera yang menentukan jenis akses ke file atau direktori yang diperlukan pemanggil. Lihat parameter DesiredAccess dari IoCreateFileEx untuk informasi selengkapnya tentang parameter ini dan untuk daftar nilai bendera.

[in] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES buram yang sudah diinisialisasi dengan InitializeObjectAttributes. Lihat parameter ObjectAttributesIoCreateFileEx untuk informasi selengkapnya dan untuk deskripsi setiap anggota struktur.

[out] IoStatusBlock

Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Lihat parameter IoStatusBlock dari IoCreateFileEx.

[in, optional] AllocationSize

Secara opsional menentukan ukuran alokasi awal dalam byte untuk file. Nilai bukan nol tidak berpengaruh kecuali file sedang dibuat, ditimpa, atau digantikan.

[in] FileAttributes

Atribut yang ditentukan secara eksplisit hanya diterapkan saat file dibuat, digantikan, atau, dalam beberapa kasus, ditimpa. Secara default, nilai ini FILE_ATTRIBUTE_NORMAL, yang dapat ditimpa oleh kombinasi ORed dari satu atau beberapa bendera FILE_ATTRIBUTE_XXX , yang didefinisikan dalam Wdm.h. Untuk daftar bendera yang dapat digunakan dengan IoCreateFile, lihat CreateFile.

[in] ShareAccess

Menentukan jenis akses berbagi ke file yang diperlukan pemanggil, sebagai nol atau satu, atau kombinasi bendera. Lihat parameter ShareAccess dari IoCreateFileEx untuk detail selengkapnya dan untuk daftar bendera.

[in] Disposition

Menentukan nilai yang menentukan tindakan yang akan diambil, bergantung pada apakah file sudah ada. Lihat parameter DisposisiIoCreateFileEx untuk daftar nilai yang mungkin.

[in] CreateOptions

Menentukan opsi yang akan diterapkan saat membuat atau membuka file. Parameter ini adalah kombinasi yang kompatibel dari bendera yang tercantum dan dijelaskan dalam parameter CreateOptions dari IoCreateFileEx.

[in, optional] EaBuffer

Untuk driver perangkat dan perantara, parameter ini harus berupa penunjuk NULL .

[in] EaLength

Untuk driver perangkat dan perantara, parameter ini harus nol.

[in] CreateFileType

Driver harus mengatur parameter ini ke CreateFileTypeNone.

[in, optional] InternalParameters

Driver harus mengatur parameter ini ke NULL.

[in] Options

Menentukan opsi yang akan digunakan selama pembuatan permintaan pembuatan. Lihat parameter OpsiIoCreateFileEx untuk daftar opsi yang mungkin.

Nilai kembali

IoCreateFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Nilai NTSTATUS. Lihat bagian Nilai Pengembaliandari IoCreateFileEx untuk daftar kemungkinan kode pengembalian.

Keterangan

Rutinitas IoCreateFileEx mirip dengan rutinitas IoCreateFile tetapi menyediakan fungsionalitas yang lebih besar daripada rutinitas IoCreateFile , termasuk akses ke parameter buat ekstra (ECP), objek perangkat, dan informasi transaksi.

Handel yang diperoleh oleh IoCreateFile dapat digunakan oleh panggilan berikutnya untuk memanipulasi data dalam file atau status atau atribut objek file.

Ada dua cara alternatif untuk menentukan nama file yang akan dibuat atau dibuka dengan IoCreateFile:

Sebagai nama jalur yang sepenuhnya memenuhi syarat, disediakan di anggota ObjectName dari objectAttributes input
Sebagai nama jalur relatif terhadap file direktori yang diwakili oleh handel di anggota RootDirectory dari input ObjectAttributes

Bendera DesiredAccess tertentu dan kombinasi bendera memiliki efek berikut:

Agar penelepon menyinkronkan penyelesaian I/O dengan menunggu FileHandle yang dikembalikan, bendera SYNCHRONIZE harus diatur. Jika tidak, penelepon yang merupakan perangkat atau driver perantara harus menyinkronkan penyelesaian I/O dengan menggunakan objek peristiwa.
Jika hanya bendera FILE_APPEND_DATA dan SYNCHRONIZE yang diatur, pemanggil hanya dapat menulis ke akhir file, dan informasi offset tentang penulisan ke file diabaikan. Namun, file akan secara otomatis diperluas seperlunya untuk jenis operasi tulis ini.
Mengatur bendera FILE_WRITE_DATA untuk file juga memungkinkan penulisan di luar akhir file terjadi. File secara otomatis diperluas untuk jenis penulisan ini.
Jika hanya bendera FILE_EXECUTE dan SYNCHRONIZE yang diatur, pemanggil tidak dapat langsung membaca atau menulis data apa pun dalam file menggunakan FileHandle yang dikembalikan: yaitu, semua operasi pada file terjadi melalui pager sistem sebagai respons terhadap instruksi dan akses data. Driver perangkat dan perantara tidak boleh mengatur bendera FILE_EXECUTE di DesiredAccess.

Parameter ShareAccess menentukan apakah utas terpisah dapat mengakses file yang sama, mungkin secara bersamaan. Asalkan kedua pembuka file memiliki hak istimewa untuk mengakses file dengan cara yang ditentukan, file dapat berhasil dibuka dan dibagikan. Jika pemanggil asli IoCreateFile tidak menentukan FILE_SHARE_READ, FILE_SHARE_WRITE, atau FILE_SHARE_DELETE, tidak ada operasi terbuka lain yang dapat dilakukan pada file: yaitu, pemanggil asli diberikan akses eksklusif ke file.

Agar file bersama berhasil dibuka, DesiredAccess yang diminta ke file harus kompatibel dengan spesifikasi DesiredAccess dan ShareAccess dari semua bukaan sebelumnya yang belum dirilis dengan ZwClose. Artinya, DesiredAccess yang ditentukan ke IoCreateFile untuk file tertentu tidak boleh bertentangan dengan akses yang tidak diizinkan oleh pembuka lain dari file.

Nilai Disposisi FILE_SUPERSEDE mengharuskan penelepon memiliki akses DELETE ke objek file yang ada. Jika demikian, panggilan yang berhasil ke IoCreateFile dengan FILE_SUPERSEDE pada file yang ada secara efektif menghapus file tersebut, lalu membuatnya kembali. Ini menyiratkan bahwa, jika file telah dibuka oleh utas lain, file akan dibuka dengan menentukan parameter ShareAccessdengan set bendera FILE_SHARE_DELETE. Perhatikan bahwa jenis disposisi ini konsisten dengan gaya POSIX menimpa file.

Nilai Disposisi FILE_OVERWRITE_IF dan FILE_SUPERSEDE serupa. Jika IoCreateFile dipanggil dengan file yang ada dan salah satu nilai Disposisi ini, file akan diganti.

Menimpa file secara semantik setara dengan operasi penggantian, kecuali untuk hal berikut:

Pemanggil harus memiliki akses tulis ke file, bukan menghapus akses. Ini menyiratkan bahwa, jika file telah dibuka oleh utas lain, file akan dibuka dengan bendera FILE_SHARE_WRITE yang diatur dalam input ShareAccess.
Atribut file yang ditentukan secara logis ORed dengan yang sudah ada di file. Ini menyiratkan bahwa, jika file telah dibuka oleh utas lain, penelepon berikutnya dari IoCreateFile tidak dapat menonaktifkan bendera FileAttributes yang ada tetapi dapat mengaktifkan bendera tambahan untuk file yang sama.

Nilai FILE_DIRECTORY_FILE CreateOptions menentukan bahwa file yang akan dibuat atau dibuka adalah file direktori. Ketika file direktori dibuat, sistem file membuat struktur yang sesuai pada disk untuk mewakili direktori kosong untuk struktur on-disk sistem file tertentu. Jika opsi ini ditentukan dan file yang diberikan untuk dibuka bukan file direktori, atau jika pemanggil menentukan nilai CreateOptions atau Disposition yang tidak konsisten, panggilan ke IoCreateFile akan gagal.

Bendera CreateOptions FILE_NO_INTERMEDIATE_BUFFERING mencegah sistem file melakukan buffer perantara atas nama pemanggil. Menentukan nilai ini menempatkan batasan tertentu pada parameter pemanggil ke rutinitas FileXxxZw , termasuk yang berikut ini:

ByteOffset opsional apa pun yang diteruskan ke ZwReadFile atau ZwWriteFile harus merupakan integral dari ukuran sektor.
Panjang yang diteruskan ke ZwReadFile atau ZwWriteFile, harus merupakan integral dari ukuran sektor. Perhatikan bahwa menentukan operasi baca ke buffer yang panjangnya persis dengan ukuran sektor dapat mengakibatkan lebih sedikit jumlah byte signifikan yang ditransfer ke buffer tersebut jika akhir file tercapai selama transfer.
Buffer harus diselaraskan sesuai dengan persyaratan keselarasan perangkat yang mendasar. Informasi ini dapat diperoleh dengan memanggil IoCreateFile untuk mendapatkan handel untuk objek file yang mewakili perangkat fisik, dan, kemudian, memanggil ZwQueryInformationFile dengan handel tersebut. Untuk daftar nilai FILE_XXX_ALIGNMENT sistem, lihat DEVICE_OBJECT.
Panggilan ke ZwSetInformationFile dengan parameter FileInformationClass yang diatur ke FilePositionInformation harus menentukan offset yang merupakan integral dari ukuran sektor.

CreateOptions FILE_SYNCHRONOUS_IO_ALERT dan FILE_SYNCHRONOUS_IO_NONALERT, yang saling eksklusif seperti namanya, tentukan bahwa semua operasi I/O pada file harus sinkron selama terjadi melalui objek file yang disebutkan oleh FileHandle yang dikembalikan. Semua I/O pada file tersebut diserialisasikan di semua utas menggunakan handel yang dikembalikan. Dengan salah satu CreateOptions ini, bendera DesiredAccess SYNCHRONIZE harus diatur sehingga manajer I/O akan menggunakan objek file sebagai objek sinkronisasi. Dengan salah satu set CreateOptions ini, manajer I/O mempertahankan "konteks posisi file" untuk objek file, offset posisi file internal saat ini. Offset ini dapat digunakan dalam panggilan ke ZwReadFile dan ZwWriteFile. Posisinya juga dapat dikueri atau diatur dengan ZwQueryInformationFile dan ZwSetInformationFile.

Jika bendera CreateOptions FILE_OPEN_REPARSE_POINT tidak ditentukan dan IoCreateFile mencoba membuka file dengan titik pemilah ulang, pemrosesan titik pemilah ulang normal terjadi untuk file. Jika, di sisi lain, bendera FILE_OPEN_REPARSE_POINT ditentukan, pemrosesan reparse normal tidak terjadi dan IoCreateFile mencoba untuk langsung membuka file titik reparse. Dalam kedua kasus, jika operasi terbuka berhasil, IoCreateFile mengembalikan STATUS_SUCCESS; jika tidak, rutinitas mengembalikan kode kesalahan NTSTATUS. IoCreateFile tidak pernah mengembalikan STATUS_REPARSE.

Bendera CreateOptions FILE_OPEN_REQUIRING_OPLOCK menghilangkan waktu antara saat Anda membuka file dan meminta oplock yang berpotensi memungkinkan pihak ketiga untuk membuka file dan mendapatkan pelanggaran berbagi. Aplikasi dapat menggunakan bendera FILE_OPEN_REQUIRING_OPLOCK pada IoCreateFile lalu meminta oplock apa pun. Ini memastikan bahwa pemilik oplock akan diberi tahu tentang permintaan terbuka nanti yang menyebabkan pelanggaran berbagi.

Di Windows 7, jika handel lain ada pada file ketika aplikasi menggunakan bendera FILE_OPEN_REQUIRING_OPLOCK, operasi pembuatan akan gagal dengan STATUS_OPLOCK_NOT_GRANTED. Pembatasan ini sudah tidak ada lagi dimulai dengan Windows 8.

Jika operasi pembuatan ini akan merusak oplock yang sudah ada pada file, maka mengatur bendera FILE_OPEN_REQUIRING_OPLOCK akan menyebabkan operasi pembuatan gagal dengan STATUS_CANNOT_BREAK_OPLOCK. Oplock yang ada tidak akan rusak oleh operasi pembuatan ini.

Aplikasi yang menggunakan bendera FILE_OPEN_REQUIRING_OPLOCK harus meminta oplock setelah panggilan ini berhasil, atau semua upaya berikutnya untuk membuka file akan diblokir tanpa manfaat pemrosesan oplock normal. Demikian pula, jika panggilan ini berhasil tetapi permintaan oplock berikutnya gagal, aplikasi yang menggunakan bendera ini harus menutup handelnya setelah mendeteksi bahwa permintaan oplock telah gagal.

Bendera FILE_OPEN_REQUIRING_OPLOCK tersedia di Windows 7, Windows Server 2008 R2 dan versi Windows yang lebih baru. Sistem file Microsoft yang mengimplementasikan bendera ini di Windows 7 adalah NTFS, FAT, dan exFAT.

Bendera CreateOptions , FILE_RESERVE_OPFILTER, memungkinkan aplikasi untuk meminta oplock tingkat 1, batch, atau filter untuk mencegah aplikasi lain mendapatkan pelanggaran berbagi. Namun, FILE_RESERVE_OPFILTER hanya berguna untuk oplock filter. Untuk menggunakannya, Anda harus mengikuti langkah-langkah berikut:

Terbitkan permintaan buat dengan CreateOptions FILE_RESERVE_OPFILTER, DesiredAccess dari FILE_READ_ATTRIBUTES, dan ShareAccess dari FILE_SHARE_READ yang tepat | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Jika sudah ada handel terbuka, permintaan buat gagal dengan STATUS_OPLOCK_NOT_GRANTED, dan oplock yang diminta berikutnya juga gagal.
- Jika Anda membuka dengan lebih banyak akses atau lebih sedikit berbagi juga akan menyebabkan kegagalan STATUS_OPLOCK_NOT_GRANTED.
Jika permintaan pembuatan berhasil, minta oplock.
Buka handel lain ke file untuk melakukan I/O.

Langkah 3 membuat ini praktis hanya untuk oplock filter. Handel yang dibuka di langkah 3 dapat memiliki DesiredAccess yang berisi maksimum FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | MENYINKRONKAN | READ_CONTROL dan masih tidak merusak oplock filter. Namun, DesiredAccess apa pun yang lebih besar dari FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE akan merusak oplock tingkat 1 atau batch dan membuat bendera FILE_RESERVE_OPFILTER tidak berguna untuk jenis oplock tersebut.

Bendera Opsi IO_NO_PARAMETER_CHECKING dapat berguna jika driver mengeluarkan permintaan pembuatan mode kernel atas nama operasi yang dimulai oleh aplikasi mode pengguna. Karena permintaan terjadi dalam konteks mode pengguna, manajer I/O, secara default, memeriksa nilai parameter yang disediakan, yang dapat menyebabkan pelanggaran akses jika parameter adalah alamat mode kernel. Bendera ini memungkinkan penelepon untuk mengambil alih perilaku default ini dan menghindari pelanggaran akses.

Untuk membuat permintaan yang berasal dari mode pengguna, jika driver mengatur IO_NO_PARAMETER_CHECKING dan IO_FORCE_ACCESS_CHECK dalam parameter OpsiIoCreateFile maka itu juga harus mengatur OBJ_FORCE_ACCESS_CHECK dalam parameter ObjectAttributes . Untuk informasi tentang bendera ini, lihat anggota AtributOBJECT_ATTRIBUTES.

NTFS adalah satu-satunya sistem file Microsoft yang menerapkan FILE_RESERVE_OPFILTER.

Rutinitas driver yang berjalan dalam konteks proses selain dari proses sistem harus mengatur atribut OBJ_KERNEL_HANDLE untuk parameter ObjectAttributesIoCreateFile. Ini membatasi penggunaan handel yang dikembalikan oleh IoCreateFile untuk memproses yang hanya berjalan dalam mode kernel. Jika tidak, handel dapat diakses oleh proses dalam konteks driver yang berjalan. Driver dapat memanggil InitializeObjectAttributes untuk mengatur atribut OBJ_KERNEL_HANDLE sebagai berikut.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)