Fungsi WriteFile (fileapi.h)
Menulis data ke file atau perangkat input/output (I/O) yang ditentukan.
Fungsi ini dirancang untuk operasi sinkron dan asinkron. Untuk fungsi serupa yang dirancang hanya untuk operasi asinkron, lihat WriteFileEx.
Sintaks
BOOL WriteFile(
[in] HANDLE hFile,
[in] LPCVOID lpBuffer,
[in] DWORD nNumberOfBytesToWrite,
[out, optional] LPDWORD lpNumberOfBytesWritten,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
Parameter
[in] hFile
Handel ke file atau perangkat I/O (misalnya, file, aliran file, disk fisik, volume, buffer konsol, drive pita, soket, sumber daya komunikasi, mailslot, atau pipa).
Parameter hFile harus dibuat dengan akses tulis. Untuk informasi selengkapnya, lihat Hak Akses Generik dan Keamanan File dan Hak Akses.
Untuk operasi penulisan asinkron, hFile dapat menjadi handel apa pun yang dibuka dengan fungsi CreateFile menggunakan bendera FILE_FLAG_OVERLAPPED atau handel soket yang dikembalikan oleh soket atau fungsi terima .
[in] lpBuffer
Penunjuk ke buffer yang berisi data yang akan ditulis ke file atau perangkat.
Buffer ini harus tetap valid selama durasi operasi tulis. Pemanggil tidak boleh menggunakan buffer ini sampai operasi tulis selesai.
[in] nNumberOfBytesToWrite
Jumlah byte yang akan ditulis ke file atau perangkat.
Nilai nol menentukan operasi tulis null. Perilaku operasi penulisan null tergantung pada sistem file atau teknologi komunikasi yang mendasar.
Windows Server 2003 dan Windows XP: Operasi penulisan pipa di seluruh jaringan berukuran terbatas per tulis. Jumlahnya bervariasi per platform. Untuk platform x86 adalah 63,97 MB. Untuk platform x64, ukurannya adalah 31,97 MB. Untuk Itanium itu 63,95 MB. Untuk informasi selengkapnya mengenai pipa, lihat bagian Keterangan.
[out, optional] lpNumberOfBytesWritten
Penunjuk ke variabel yang menerima jumlah byte yang ditulis saat menggunakan parameter hFile sinkron. WriteFile menetapkan nilai ini ke nol sebelum melakukan pemeriksaan kesalahan atau pekerjaan apa pun. Gunakan NULL untuk parameter ini jika ini adalah operasi asinkron untuk menghindari hasil yang berpotensi keliru.
Parameter ini hanya dapat null ketika parameter lpOverlapped bukan NULL.
Windows 7: Parameter ini tidak boleh NULL.
Untuk informasi lebih lanjut, lihat bagian Keterangan.
[in, out, optional] lpOverlapped
Penunjuk ke struktur YANG TUMPANG TINDIH diperlukan jika parameter hFile dibuka dengan FILE_FLAG_OVERLAPPED, jika tidak, parameter ini bisa NULL.
Untuk hFile yang mendukung offset byte, jika Anda menggunakan parameter ini, Anda harus menentukan offset byte untuk mulai menulis ke file atau perangkat. Offset ini ditentukan dengan mengatur anggota Offset dan OffsetHigh dari struktur yang TUMPANG TINDIH . Untuk hFile yang tidak mendukung offset byte, Offset dan OffsetHigh diabaikan.
Untuk menulis ke akhir file, tentukan anggota Offset dan OffsetHigh dari struktur TUMPANG TINDIH sebagai 0xFFFFFFFF. Ini secara fungsional setara dengan sebelumnya memanggil fungsi CreateFile untuk membuka hFile menggunakan akses FILE_APPEND_DATA .
Untuk informasi selengkapnya tentang kombinasi lpOverlapped dan FILE_FLAG_OVERLAPPED yang berbeda, lihat bagian Keterangan dan bagian Sinkronisasi dan Posisi File .
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).
Jika fungsi gagal, atau selesai secara asinkron, nilai yang dikembalikan adalah nol (FALSE). Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .
Keterangan
Fungsi WriteFile mengembalikan ketika salah satu kondisi berikut terjadi:
- Jumlah byte yang diminta ditulis.
- Operasi baca melepaskan ruang buffer pada ujung baca pipa (jika tulisan diblokir). Untuk informasi selengkapnya, lihat bagian Pipa .
- Handel asinkron sedang digunakan dan tulisan terjadi secara asinkron.
- Muncul kesalahan.
Untuk membatalkan semua operasi I/O asinkron yang tertunda, gunakan:
- CancelIo—fungsi ini hanya membatalkan operasi yang dikeluarkan oleh utas panggilan untuk handel file yang ditentukan.
- CancelIoEx—fungsi ini membatalkan semua operasi yang dikeluarkan oleh utas untuk handel file yang ditentukan.
Operasi I/O yang dibatalkan selesai dengan kesalahan ERROR_OPERATION_ABORTED.
Fungsi WriteFile mungkin gagal dengan ERROR_NOT_ENOUGH_QUOTA, yang berarti buffer proses panggilan tidak dapat dikunci halaman. Untuk informasi selengkapnya, lihat SetProcessWorkingSetSize.
Jika bagian dari file dikunci oleh proses lain dan operasi tulis tumpang tindih dengan bagian terkunci, WriteFile gagal.
Saat menulis ke file, waktu tulis terakhir tidak sepenuhnya diperbarui sampai semua handel yang digunakan untuk menulis telah ditutup. Oleh karena itu, untuk memastikan waktu penulisan terakhir yang akurat, tutup handel file segera setelah menulis ke file.
Mengakses buffer output saat operasi tulis menggunakan buffer dapat menyebabkan kerusakan data yang ditulis dari buffer tersebut. Aplikasi tidak boleh menulis ke, mengalokasikan ulang, atau membebaskan buffer output yang digunakan operasi tulis hingga operasi tulis selesai. Ini bisa sangat bermasalah saat menggunakan handel file asinkron. Informasi tambahan mengenai handel file sinkron versus asinkron dapat ditemukan nanti di bagian Sinkronisasi dan Posisi File dan I/O Sinkron dan Asinkron.
Perhatikan bahwa stempel waktu mungkin tidak diperbarui dengan benar untuk file jarak jauh. Untuk memastikan hasil yang konsisten, gunakan I/O yang tidak dibuffer.
Sistem menafsirkan nol byte untuk ditulis karena menentukan operasi penulisan null dan WriteFile tidak memotong atau memperluas file. Untuk memotong atau memperluas file, gunakan fungsi SetEndOfFile .
Karakter dapat ditulis ke buffer layar menggunakan WriteFile dengan handel ke output konsol. Perilaku fungsi yang tepat ditentukan oleh mode konsol. Data ditulis ke posisi kursor saat ini. Posisi kursor diperbarui setelah operasi tulis. Untuk informasi selengkapnya tentang handel konsol, lihat CreateFile.
Saat menulis ke perangkat komunikasi, perilaku WriteFile ditentukan oleh batas waktu komunikasi saat ini sebagaimana diatur dan diambil dengan menggunakan fungsi SetCommTimeouts dan GetCommTimeouts . Hasil yang tidak dapat diprediksi dapat terjadi jika Anda gagal mengatur nilai waktu habis. Untuk informasi selengkapnya tentang batas waktu komunikasi, lihat COMMTIMEOUTS.
Meskipun penulisan sektor tunggal bersifat atomik, tulisan multi-sektor tidak dijamin atom kecuali Anda menggunakan transaksi (yaitu, handel yang dibuat adalah handel yang ditransaksikan; misalnya, handel yang dibuat menggunakan CreateFileTransacted). Penulisan multi-sektor yang di-cache mungkin tidak selalu ditulis ke disk segera; oleh karena itu, tentukan FILE_FLAG_WRITE_THROUGH di CreateFile untuk memastikan bahwa seluruh penulisan multi-sektor ditulis ke disk tanpa potensi penundaan penembolokan.
Jika Anda menulis langsung ke volume yang memiliki sistem file yang dipasang, Anda harus terlebih dahulu mendapatkan akses eksklusif ke volume. Jika tidak, Anda berisiko menyebabkan kerusakan data atau ketidakstabilan sistem, karena penulisan aplikasi Anda mungkin bertentangan dengan perubahan lain yang berasal dari sistem file dan membiarkan konten volume dalam keadaan tidak konsisten. Untuk mencegah masalah ini, perubahan berikut telah dilakukan di Windows Vista dan yang lebih baru:
- Tulis pada handel volume akan berhasil jika volume tidak memiliki sistem file yang dipasang, atau jika salah satu kondisi berikut ini benar:
- Sektor yang akan ditulis adalah sektor boot.
- Sektor yang akan ditulis untuk berada di luar ruang sistem file.
- Anda telah secara eksplisit mengunci atau melepas volume dengan menggunakan FSCTL_LOCK_VOLUME atau FSCTL_DISMOUNT_VOLUME.
- Volume tidak memiliki sistem file aktual. (Dengan kata lain, ia memiliki sistem file RAW yang dipasang.)
- Penulisan pada handel disk akan berhasil jika salah satu kondisi berikut ini benar:
- Sektor yang akan ditulis tidak termasuk dalam jangkauan volume.
- Sektor yang akan ditulis berada dalam volume yang dipasang, tetapi Anda telah secara eksplisit mengunci atau melepas volume dengan menggunakan FSCTL_LOCK_VOLUME atau FSCTL_DISMOUNT_VOLUME.
- Sektor yang akan ditulis untuk jatuh dalam volume yang tidak memiliki sistem file yang dipasang selain RAW.
Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, kondisi berikut berlaku:
- Parameter lpOverlapped harus menunjuk ke struktur TUMPANG TINDIH yang valid dan unik, jika tidak, fungsi dapat salah melaporkan bahwa operasi tulis selesai.
- Parameter lpNumberOfBytesWritten harus diatur ke NULL. Untuk mendapatkan jumlah byte yang ditulis, gunakan fungsi GetOverlappedResult . Jika parameter hFile dikaitkan dengan port penyelesaian I/O, Anda juga bisa mendapatkan jumlah byte yang ditulis dengan memanggil fungsi GetQueuedCompletionStatus .
| 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 |
Sinkronisasi dan Posisi File
Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, hFile adalah handel file asinkron; jika tidak, itu sinkron. Aturan untuk menggunakan struktur TUMPANG TINDIH sedikit berbeda untuk masing-masing, seperti yang disebutkan sebelumnya.- WriteFile dapat kembali sebelum operasi tulis selesai. Dalam skenario ini, WriteFile mengembalikan FALSE dan fungsi GetLastError mengembalikan ERROR_IO_PENDING, yang memungkinkan proses panggilan berlanjut saat sistem menyelesaikan operasi tulis.
- Parameter lpOverlapped tidak boleh NULL dan harus digunakan dengan ingat fakta berikut:
- Meskipun peristiwa yang ditentukan dalam struktur TUMPANG TINDIH diatur dan diatur ulang secara otomatis oleh sistem, offset yang ditentukan dalam struktur TUMPANG TINDIH tidak diperbarui secara otomatis.
- WriteFile mengatur ulang peristiwa ke status tidak bertanda ketika memulai operasi I/O.
- Peristiwa yang ditentukan dalam struktur TUMPANG TINDIH diatur ke status bersinyali ketika operasi tulis selesai; hingga saat itu, operasi tulis dianggap tertunda.
- Karena operasi tulis dimulai pada offset yang ditentukan dalam struktur TUMPANG TINDIH , dan WriteFile dapat kembali sebelum operasi penulisan tingkat sistem selesai (tulis tertunda), offset maupun bagian lain dari struktur harus dimodifikasi, dibebaskan, atau digunakan kembali oleh aplikasi sampai peristiwa disinyalkan (yaitu, tulis selesai).
- Jika lpOverlappedNULL, operasi tulis dimulai pada posisi file saat ini dan WriteFile tidak kembali sampai operasi selesai, dan sistem memperbarui penunjuk file sebelum WriteFile kembali.
- Jika lpOverlapped bukan NULL, operasi tulis dimulai pada offset yang ditentukan dalam struktur TUMPANG TINDIH dan WriteFile tidak kembali sampai operasi tulis selesai. Sistem memperbarui bidang Internal dan InternalHigh yang TUMPANG TINDIH dan penunjuk file sebelum WriteFile kembali.
Pipa
Jika pipa anonim sedang digunakan dan handel baca telah ditutup, ketika WriteFile mencoba menulis menggunakan handel tulis yang sesuai dari pipa, fungsi mengembalikan FALSE dan GetLastError mengembalikan ERROR_BROKEN_PIPE.Jika buffer pipa penuh ketika aplikasi menggunakan fungsi WriteFile untuk menulis ke pipa, operasi tulis mungkin tidak segera selesai. Operasi tulis akan selesai ketika operasi baca (menggunakan fungsi ReadFile ) membuat lebih banyak ruang buffer sistem tersedia untuk pipa.
Saat menulis ke handel pipa mode byte non-pemblokiran dengan ruang buffer yang tidak mencukupi, WriteFile mengembalikan TRUE dengan *lpNumberOfBytesWritten<nNumberOfBytesToWrite.
Untuk informasi selengkapnya tentang pipa, lihat Pipa.
Operasi Yang Ditransaksikan
Jika ada transaksi yang terikat ke handel file, maka penulisan file akan ditransaksikan. Untuk informasi selengkapnya, lihat Tentang Transactional NTFS.Contoh
Untuk beberapa contoh, lihat Membuat dan Menggunakan File Sementara dan Membuka File untuk Membaca atau Menulis.
Contoh C++ berikut menunjukkan cara menyelaraskan sektor untuk penulisan file yang tidak dibuffer. Variabel Ukuran adalah ukuran blok data asli yang Anda minati untuk menulis ke file. Untuk aturan tambahan mengenai I/O file yang tidak dibuffer, lihat Buffering File.#include <windows.h>
#define ROUND_UP_SIZE(Value,Pow2) ((SIZE_T) ((((ULONG)(Value)) + (Pow2) - 1) & (~(((LONG)(Pow2)) - 1))))
#define ROUND_UP_PTR(Ptr,Pow2) ((void *) ((((ULONG_PTR)(Ptr)) + (Pow2) - 1) & (~(((LONG_PTR)(Pow2)) - 1))))
int main()
{
// Sample data
unsigned long bytesPerSector = 65536; // obtained from the GetFreeDiskSpace function.
unsigned long size = 15536; // Buffer size of your data to write.
// Ensure you have one more sector than Size would require.
size_t sizeNeeded = bytesPerSector + ROUND_UP_SIZE(size, bytesPerSector);
// Replace this statement with any allocation routine.
auto buffer = new uint8_t[SizeNeeded];
// Actual alignment happens here.
auto bufferAligned = ROUND_UP_PTR(buffer, bytesPerSector);
// ... Add code using bufferAligned here.
// Replace with corresponding free routine.
delete buffer;
}
Persyaratan
| Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | fileapi.h (sertakan Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk