Fungsi CreateFileMappingNumaA (winbase.h)

  • Artikel

Membuat atau membuka objek pemetaan file bernama atau tidak bernama untuk file tertentu dan menentukan simpul NUMA untuk memori fisik.

Sintaks

HANDLE CreateFileMappingNumaA(
  [in]           HANDLE                hFile,
  [in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  [in]           DWORD                 flProtect,
  [in]           DWORD                 dwMaximumSizeHigh,
  [in]           DWORD                 dwMaximumSizeLow,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 nndPreferred
);

Parameter

[in] hFile

Handel ke file untuk membuat objek pemetaan file.

File harus dibuka dengan hak akses yang kompatibel dengan bendera perlindungan yang ditentukan parameter flProtect . Ini tidak diperlukan, tetapi disarankan agar file yang ingin Anda petakan dibuka untuk akses eksklusif. Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

Jika hFileINVALID_HANDLE_VALUE, proses panggilan juga harus menentukan ukuran untuk objek pemetaan file di parameter dwMaximumSizeHigh dan dwMaximumSizeLow . Dalam skenario ini, CreateFileMappingNuma membuat objek pemetaan file dengan ukuran tertentu yang didukung oleh file halaman sistem alih-alih oleh file dalam sistem file.

[in, optional] lpFileMappingAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses anak. Anggota lpSecurityDescriptor dari
SECURITY_ATTRIBUTES struktur menentukan deskriptor keamanan untuk objek pemetaan file baru.

Jika lpFileMappingAttributesADALAH NULL, handel tidak dapat diwariskan dan objek pemetaan file mendapatkan deskriptor keamanan default. Daftar kontrol akses (ACL) di deskriptor keamanan default untuk objek pemetaan file berasal dari token utama atau peniruan dari pembuat. Untuk informasi selengkapnya, lihat Keamanan Pemetaan File dan Hak Akses.

[in] flProtect

Menentukan perlindungan halaman objek pemetaan file. Semua tampilan objek yang dipetakan harus kompatibel dengan perlindungan ini.

Parameter ini bisa menjadi salah satu nilai berikut.

Nilai Makna
PAGE_EXECUTE_READ
0x20
 Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-saat-tulis, atau jalankan.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_EXECUTE .
PAGE_EXECUTE_READWRITE
0x40
 Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-tulis, baca/tulis, atau jalankan.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ, GENERIC_WRITE, dan GENERIC_EXECUTE .
PAGE_EXECUTE_WRITECOPY
0x80
 Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-saat-tulis, atau jalankan. Nilai ini setara dengan PAGE_EXECUTE_READ.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_EXECUTE .

Windows Vista: Nilai ini tidak tersedia sampai Windows Vista dengan SP1.
PAGE_READONLY
0x02
 Memungkinkan tampilan dipetakan untuk akses baca-saja atau salin-saat-tulis. Upaya untuk menulis ke wilayah tertentu menghasilkan pelanggaran akses.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ .
PAGE_READWRITE
0x04
 Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-tulis, atau baca/tulis.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_WRITE .
PAGE_WRITECOPY
0x08
 Memungkinkan tampilan dipetakan untuk akses baca-saja atau salin-saat-tulis. Nilai ini setara dengan PAGE_READONLY.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ .
 

Aplikasi dapat menentukan satu atau beberapa atribut berikut untuk objek pemetaan file dengan menggabungkannya dengan salah satu nilai perlindungan halaman sebelumnya.

Nilai Makna
SEC_COMMIT
0x8000000
 Mengalokasikan penyimpanan fisik dalam memori atau file halaman untuk semua halaman.

Ini adalah pengaturan default.
SEC_IMAGE
0x1000000
 Mengatur file yang ditentukan menjadi file gambar yang dapat dieksekusi.

Atribut SEC_IMAGE harus dikombinasikan dengan nilai perlindungan halaman seperti PAGE_READONLY. Namun, nilai perlindungan halaman ini tidak berpengaruh pada tampilan file gambar yang dapat dieksekusi. Perlindungan halaman untuk tampilan file gambar yang dapat dieksekusi ditentukan oleh file yang dapat dieksekusi itu sendiri.

Tidak ada atribut lain yang valid dengan SEC_IMAGE.
SEC_IMAGE_NO_EXECUTE
0x11000000
 Menentukan bahwa file yang ditentukan parameter hFile adalah file gambar yang dapat dieksekusi yang tidak akan dijalankan dan file gambar yang dimuat tidak akan memiliki pemeriksaan integritas paksa yang dijalankan. Selain itu, memetakan tampilan objek pemetaan file yang dibuat dengan atribut SEC_IMAGE_NO_EXECUTE tidak akan memanggil panggilan balik driver yang terdaftar menggunakan API kernel PsSetLoadImageNotifyRoutine .

Atribut SEC_IMAGE_NO_EXECUTE harus dikombinasikan dengan nilai perlindungan halaman PAGE_READONLY . Tidak ada atribut lain yang valid dengan SEC_IMAGE_NO_EXECUTE.

Windows Server 2008 R2, Windows 7, Windows Server 2008 dan Windows Vista: Nilai ini tidak didukung sebelum Windows Server 2012 dan Windows 8.
SEC_LARGE_PAGES
0x80000000
 Memungkinkan halaman besar digunakan saat memetakan gambar atau mendukung dari pagefile, tetapi tidak saat memetakan data untuk file reguler. Pastikan untuk menentukan ukuran maksimum objek pemetaan file sebagai ukuran minimum halaman besar yang dilaporkan oleh fungsi GetLargePageMinimum dan untuk mengaktifkan hak istimewa SeLockMemoryPrivilege .
SEC_NOCACHE
0x10000000
 Mengatur semua halaman ke tidak dapat di-cache.

Aplikasi tidak boleh menggunakan bendera ini kecuali ketika secara eksplisit diperlukan untuk perangkat. Menggunakan fungsi yang saling diblokir dengan memori yang dipetakan dengan SEC_NOCACHE dapat menghasilkan pengecualian EXCEPTION_ILLEGAL_INSTRUCTION .

SEC_NOCACHE mengharuskan SEC_RESERVE atau SEC_COMMIT diatur.
SEC_RESERVE
0x4000000
 Mencadangkan semua halaman tanpa mengalokasikan penyimpanan fisik.

Rentang halaman yang dipesan tidak dapat digunakan oleh operasi alokasi lainnya hingga rentang halaman dirilis.

Halaman yang dipesan dapat diidentifikasi dalam panggilan berikutnya ke fungsi VirtualAllocExNuma . Atribut ini hanya valid jika parameter hFileINVALID_HANDLE_VALUE (yaitu, objek pemetaan file yang didukung oleh file halaman sistem).
SEC_WRITECOMBINE
0x40000000
 Mengatur semua halaman yang akan digabungkan dengan penulisan.

Aplikasi tidak boleh menggunakan atribut ini kecuali ketika secara eksplisit diperlukan untuk perangkat. Menggunakan fungsi yang saling terhubung dengan memori yang dipetakan dengan SEC_WRITECOMBINE dapat menghasilkan pengecualian EXCEPTION_ILLEGAL_INSTRUCTION .

SEC_WRITECOMBINE mengharuskan atribut SEC_RESERVE atau SEC_COMMIT diatur.

[in] dwMaximumSizeHigh

DWORD berurutan tinggi dari ukuran maksimum objek pemetaan file.

[in] dwMaximumSizeLow

DWORD berurutan rendah dari ukuran maksimum objek pemetaan file.

Jika parameter ini dan parameter dwMaximumSizeHigh adalah 0 (nol), ukuran maksimum objek pemetaan file sama dengan ukuran file saat ini yang diidentifikasi parameter hFile .

Upaya untuk memetakan file dengan panjang 0 (nol) gagal dengan kode kesalahan ERROR_FILE_INVALID. Aplikasi harus menguji file dengan panjang 0 (nol) dan menolak file-file tersebut.

[in, optional] lpName

Nama objek pemetaan file.

Jika parameter ini cocok dengan nama objek pemetaan file yang ada, fungsi meminta akses ke objek dengan perlindungan yang ditentukan parameter flProtect .

Jika parameter ini NULL, objek pemetaan file dibuat tanpa nama.

Jika parameter lpName cocok dengan nama peristiwa, semaphore, mutex, timer yang dapat di tunggu, atau objek pekerjaan yang ada, fungsi gagal dan fungsi GetLastError mengembalikan ERROR_INVALID_HANDLE. Ini terjadi karena objek ini memiliki namespace yang sama.

Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuat objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Membuat objek pemetaan file di namespace global memerlukan hak istimewa SeCreateGlobalPrivilege . Untuk informasi selengkapnya, lihat Namespace Objek Kernel.

Pengalihan pengguna cepat diimplementasikan dengan menggunakan sesi Layanan Terminal. Pengguna pertama yang masuk menggunakan sesi 0 (nol), pengguna berikutnya untuk masuk menggunakan sesi 1 (satu), dan sebagainya. Nama objek kernel harus mengikuti panduan sehingga aplikasi dapat mendukung beberapa pengguna.

[in] nndPreferred

Simpul NUMA tempat memori fisik harus berada.

Nilai Makna
NUMA_NO_PREFERRED_NODE
0xffffffff
 Tidak ada simpul NUMA yang disukai. Ini sama dengan memanggil fungsi CreateFileMapping .

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek pemetaan file.

Jika objek ada sebelum panggilan fungsi, fungsi mengembalikan handel ke objek yang ada (dengan ukurannya saat ini, bukan ukuran yang ditentukan) dan fungsi GetLastError mengembalikan ERROR_ALREADY_EXISTS.

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

Keterangan

Setelah objek pemetaan file dibuat, ukuran file tidak boleh melebihi ukuran objek pemetaan file; jika ya, tidak semua isi file tersedia untuk dibagikan.

Objek pemetaan file dapat dibagikan dengan duplikasi, pewarisan, atau berdasarkan nama. Konten awal halaman dalam objek pemetaan file yang didukung oleh file halaman adalah 0 (nol).

Jika aplikasi menentukan ukuran untuk objek pemetaan file yang lebih besar dari ukuran file bernama aktual pada disk dan jika perlindungan halaman memungkinkan akses tulis (yaitu, parameter flProtect menentukan PAGE_READWRITE atau PAGE_EXECUTE_READWRITE), maka file pada disk ditingkatkan agar sesuai dengan ukuran objek pemetaan file yang ditentukan. Jika file diperluas, konten file antara akhir lama file dan akhir baru file tidak dijamin nol; perilaku ditentukan oleh sistem file.

Jika file tidak dapat ditingkatkan, hasilnya adalah kegagalan untuk membuat objek pemetaan file dan fungsi GetLastError mengembalikan ERROR_DISK_FULL.

Handel yang dikembalikan fungsi CreateFileMappingNuma memiliki akses penuh ke objek pemetaan file baru dan dapat digunakan dengan fungsi apa pun yang memerlukan handel ke objek pemetaan file. Objek pemetaan file dapat dibagikan melalui pembuatan proses, menangani duplikasi, atau berdasarkan nama. Untuk informasi selengkapnya, lihat fungsi DuplicateHandle dan OpenFileMapping .

Membuat objek pemetaan file membuat potensi untuk memetakan tampilan file tetapi tidak memetakan tampilan. Fungsi MapViewOfFileExNuma memetakan tampilan file ke dalam ruang alamat proses.

Dengan satu pengecualian penting, tampilan file yang berasal dari satu objek pemetaan file bersifat koheren atau identik pada waktu tertentu. Jika beberapa proses memiliki penanganan objek pemetaan file yang sama, mereka akan melihat tampilan data yang koheren saat memetakan tampilan file.

Pengecualian terkait dengan file jarak jauh. Meskipun fungsi CreateFileMappingNuma berfungsi dengan file jarak jauh, fungsi ini tidak membuatnya tetap koheren. Misalnya, jika dua komputer memetakan file sebagai dapat ditulis dan keduanya mengubah halaman yang sama, setiap komputer hanya melihat tulisannya sendiri ke halaman. Ketika data diperbarui pada disk, halaman tidak digabungkan.

File yang dipetakan dan file yang diakses dengan menggunakan fungsi input dan output (I/O) (ReadFile dan WriteFile) belum tentu koheren.

Untuk sepenuhnya menutup objek pemetaan file, aplikasi harus membatalkan peta semua tampilan objek pemetaan file dengan memanggil fungsi UnmapViewOfFile lalu menutup handel objek pemetaan file dengan memanggil fungsi CloseHandle .

Fungsi-fungsi ini dapat dipanggil dalam urutan apa pun. Panggilan ke fungsi UnmapViewOfFile diperlukan, karena tampilan objek pemetaan file yang dipetakan mempertahankan handel terbuka internal ke objek, dan objek pemetaan file tidak ditutup sampai semua handel terbuka ditutup.

Saat memodifikasi file melalui tampilan yang dipetakan, tanda waktu modifikasi terakhir mungkin tidak diperbarui secara otomatis. Jika diperlukan, pemanggil harus menggunakan SetFileTime untuk mengatur tanda waktu.

Membuat objek pemetaan file dari sesi selain sesi nol memerlukan hak istimewa SeCreateGlobalPrivilege . Perhatikan bahwa pemeriksaan hak istimewa ini terbatas pada pembuatan objek pemetaan file dan tidak berlaku untuk membuka objek yang sudah ada. Misalnya, jika layanan atau sistem membuat objek pemetaan file, proses apa pun yang berjalan dalam sesi apa pun dapat mengakses objek pemetaan file asalkan pemanggil memiliki hak akses yang diperlukan.

Gunakan penanganan pengecualian terstruktur untuk melindungi kode apa pun yang menulis atau membaca dari tampilan yang dipetakan memori. Untuk informasi selengkapnya, lihat Membaca dan Menulis Dari Tampilan File.

Untuk memiliki pemetaan dengan izin yang dapat dieksekusi, aplikasi harus memanggil fungsi CreateFileMappingNuma dengan PAGE_EXECUTE_READWRITE atau PAGE_EXECUTE_READ lalu memanggil fungsi MapViewOfFileExNuma dengan FILE_MAP_EXECUTE | FILE_MAP_WRITE atau FILE_MAP_EXECUTE | FILE_MAP_READ.

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

Teknologi Didukung
Protokol Server Message Block (SMB) 3.0 Ya
SMB 3.0 Transparent Failover (TFO) Ya
SMB 3.0 dengan Berbagi File Peluasan Skala (SO) Ya
Sistem File Volume Bersama Kluster (CsvFS) Ya
Sistem File Tangguh (ReFS) Ya

Persyaratan

   
Klien minimum yang didukung Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Target Platform Windows
Header winbase.h (termasuk Windows.h, Memoryapi.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

CloseHandle

CreateFileMapping

DuplikatHandle

Fungsi Pemetaan File

MapViewOfFileExNuma

Dukungan NUMA

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAllocExNuma

WriteFile