Bagikan melalui

Fungsi WriteFile (fileapi.h)

  • Artikel

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.

Sintaksis

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, tape drive, 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 berupa handel apa pun yang dibuka dengan fungsi CreateFile menggunakan bendera FILE_FLAG_OVERLAPPED atau handel soket yang dikembalikan oleh soket atau menerima fungsi.

[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 dibatasi ukurannya per penulisan. Jumlahnya bervariasi per platform. Untuk platform x86 adalah 63,97 MB. Untuk platform x64, ini 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 salah.

Parameter ini dapat NULL hanya ketika parameter lpOverlapped tidak NULL.

Windows 7: Parameter ini tidak dapat NULL.

Untuk informasi selengkapnya, lihat bagian Keterangan.

[in, out, optional] lpOverlapped

Penunjuk ke struktur TUMPANG TINDIH diperlukan jika parameter hFile dibuka dengan FILE_FLAG_OVERLAPPED, jika tidak, parameter ini dapat 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 Offset dan OffsetHigh anggota struktur TUMPANG TINDIH. Untuk hFile yang tidak mendukung offset byte, Offset dan OffsetHigh diabaikan.

Untuk menulis ke akhir file, tentukan Offset dan OffsetHigh anggota 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, lihat bagian Keterangan dan bagian Sinkronisasi dan Posisi File.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian bukan nol (TRUE).

Jika fungsi gagal, atau menyelesaikan secara asinkron, nilai yang dikembalikan adalah nol (FALSE). Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .

Catatan ERROR_IO_PENDING kode GetLastError bukanlah kegagalan; ini menunjuk operasi tulis tertunda penyelesaiannya secara asinkron. Untuk informasi selengkapnya, lihat Keterangan.
 

Komentar

Fungsi WriteFile mengembalikan ketika salah satu kondisi berikut terjadi:

  • Jumlah byte yang diminta ditulis.
  • Operasi baca melepaskan ruang buffer pada ujung baca pipa (jika tulis diblokir). Untuk informasi selengkapnya, lihat bagian Pipes.
  • Handel asinkron sedang digunakan dan penulisan terjadi secara asinkron.
  • Terjadi kesalahan.
Fungsi WriteFile mungkin gagal dengan ERROR_INVALID_USER_BUFFER atau ERROR_NOT_ENOUGH_MEMORY setiap kali ada terlalu banyak permintaan I/O asinkron yang luar biasa.

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.
Gunakan fungsi CancelSynchronousIo untuk membatalkan operasi I/O sinkron yang tertunda.

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 menginterpretasikan 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 atomik 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 dalam 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:

  • Penulisan 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 untuk jatuh 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.
Ada persyaratan ketat untuk berhasil bekerja dengan file yang dibuka dengan CreateFile menggunakan FILE_FLAG_NO_BUFFERING. Untuk detailnya, lihat Buffering File .

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, kondisi berikut berlaku:

  • Parameter lpOverlapped harus menunjuk ke struktur yang valid dan unik TUMPANG TINDIH, jika tidak, fungsi dapat salah melaporkan bahwa operasi penulisan 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.
Di 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
 

Sinkronisasi dan Posisi File

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, itu adalah handel file asinkron; jika tidak, itu sinkron. Aturan untuk menggunakan struktur TUMPANG TINDIH sedikit berbeda untuk masing-masing, seperti yang disebutkan sebelumnya.
Catatan Jika file atau perangkat dibuka untuk I/O asinkron, panggilan berikutnya ke fungsi seperti WriteFile menggunakan handel tersebut umumnya segera kembali, tetapi juga dapat berperilaku sinkron sehubungan dengan eksekusi yang diblokir. Untuk informasi selengkapnya, lihat I/O disk asinkron muncul sebagai sinkron di Windows.
 
Pertimbangan untuk bekerja dengan handel file asinkron:
  • 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 yang disinyalir ketika operasi tulis selesai; sampai 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), baik offset maupun bagian lain dari struktur harus dimodifikasi, dibebaskan, atau digunakan kembali oleh aplikasi sampai peristiwa disinyalir (yaitu, tulis selesai).
Pertimbangan untuk bekerja dengan handel file sinkron:
  • Jika lpOverlapped null, 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 tidak null, operasi tulis dimulai pada offset yang ditentukan dalam struktur TUMPANG TINDIH dan WriteFile tidak kembali sampai operasi penulisan selesai. Sistem memperbarui bidang TUMPANG TINDIH Internal dan InternalHigh dan penunjuk file sebelum WriteFile kembali.
Untuk informasi selengkapnya, lihat CreateFile dan I/O Sinkron dan Asinkron .

Pipa

Jika pipa anonim sedang digunakan dan handel baca telah ditutup, ketika WriteFile mencoba menulis menggunakan handel tulis terkait 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 yang 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 Pipes.

Operasi Ditransaksikan

Jika ada transaksi yang terikat ke handel file, maka penulisan file ditransaksikan. Untuk informasi selengkapnya, lihat TentangTransaksi 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 File Buffering. 
#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

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

Lihat juga

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

CreateFileTransacted

File Management Functions

GetLastError

GetOverlappedResult

GetQueuedCompletionStatus

ReadFile

SetEndOfFile

WriteFileEx