WriteFile function (fileapi.h)

Writes data to the specified file or input/output (I/O) device.

This function is designed for both synchronous and asynchronous operation. For a similar function designed solely for asynchronous operation, see WriteFileEx.

Syntax

Parameters

A handle to the file or I/O device (for example, a file, file stream, physical disk, volume, console buffer, tape drive, socket, communications resource, mailslot, or pipe).

The hFile parameter must have been created with the write access. For more information, see Generic Access Rights and File Security and Access Rights.

For asynchronous write operations, hFile can be any handle opened with the CreateFile function using the FILE_FLAG_OVERLAPPED flag or a socket handle returned by the socket or accept function.

A pointer to the buffer containing the data to be written to the file or device.

This buffer must remain valid for the duration of the write operation. The caller must not use this buffer until the write operation is completed.

The number of bytes to be written to the file or device.

A value of zero specifies a null write operation. The behavior of a null write operation depends on the underlying file system or communications technology.

Windows ServerВ 2003 and WindowsВ XP:В В Pipe write operations across a network are limited in size per write. The amount varies per platform. For x86 platforms it’s 63.97 MB. For x64 platforms it’s 31.97 MB. For Itanium it’s 63.95 MB. For more information regarding pipes, see the Remarks section.

A pointer to the variable that receives the number of bytes written when using a synchronous hFile parameter. WriteFile sets this value to zero before doing any work or error checking. Use NULL for this parameter if this is an asynchronous operation to avoid potentially erroneous results.

This parameter can be NULL only when the lpOverlapped parameter is not NULL.

For more information, see the Remarks section.

A pointer to an OVERLAPPED structure is required if the hFile parameter was opened with FILE_FLAG_OVERLAPPED, otherwise this parameter can be NULL.

For an hFile that supports byte offsets, if you use this parameter you must specify a byte offset at which to start writing to the file or device. This offset is specified by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For an hFile that does not support byte offsets, Offset and OffsetHigh are ignored.

To write to the end of file, specify both the Offset and OffsetHigh members of the OVERLAPPED structure as 0xFFFFFFFF. This is functionally equivalent to previously calling the CreateFile function to open hFile using FILE_APPEND_DATA access.

For more information about different combinations of lpOverlapped and FILE_FLAG_OVERLAPPED, see the Remarks section and the Synchronization and File Position section.

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, or is completing asynchronously, the return value is zero (FALSE). To get extended error information, call the GetLastError function.

Remarks

The WriteFile function returns when one of the following conditions occur:

• The number of bytes requested is written.
• A read operation releases buffer space on the read end of the pipe (if the write was blocked). For more information, see the Pipes section.
• An asynchronous handle is being used and the write is occurring asynchronously.
• An error occurs.

The WriteFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

To cancel all pending asynchronous I/O operations, use either:

• CancelIo—this function cancels only operations issued by the calling thread for the specified file handle.
• CancelIoEx—this function cancels all operations issued by the threads for the specified file handle.

Use the CancelSynchronousIo function to cancel pending synchronous I/O operations.

I/O operations that are canceled complete with the error ERROR_OPERATION_ABORTED.

The WriteFile function may fail with ERROR_NOT_ENOUGH_QUOTA, which means the calling process’s buffer could not be page-locked. For more information, see SetProcessWorkingSetSize.

If part of the file is locked by another process and the write operation overlaps the locked portion, WriteFile fails.

When writing to a file, the last write time is not fully updated until all handles used for writing have been closed. Therefore, to ensure an accurate last write time, close the file handle immediately after writing to the file.

Accessing the output buffer while a write operation is using the buffer may lead to corruption of the data written from that buffer. Applications must not write to, reallocate, or free the output buffer that a write operation is using until the write operation completes. This can be particularly problematic when using an asynchronous file handle. Additional information regarding synchronous versus asynchronous file handles can be found later in the Synchronization and File Position section and Synchronous and Asynchronous I/O.

Note that the time stamps may not be updated correctly for a remote file. To ensure consistent results, use unbuffered I/O.

The system interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

Characters can be written to the screen buffer using WriteFile with a handle to console output. The exact behavior of the function is determined by the console mode. The data is written to the current cursor position. The cursor position is updated after the write operation. For more information about console handles, see CreateFile.

When writing to a communications device, the behavior of WriteFile is determined by the current communication time-out as set and retrieved by using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the time-out values. For more information about communication time-outs, see COMMTIMEOUTS.

Although a single-sector write is atomic, a multi-sector write is not guaranteed to be atomic unless you are using a transaction (that is, the handle created is a transacted handle; for example, a handle created using CreateFileTransacted). Multi-sector writes that are cached may not always be written to the disk right away; therefore, specify FILE_FLAG_WRITE_THROUGH in CreateFile to ensure that an entire multi-sector write is written to the disk without potential caching delays.

If you write directly to a volume that has a mounted file system, you must first obtain exclusive access to the volume. Otherwise, you risk causing data corruption or system instability, because your application’s writes may conflict with other changes coming from the file system and leave the contents of the volume in an inconsistent state. To prevent these problems, the following changes have been made in WindowsВ Vista and later:

• A write on a volume handle will succeed if the volume does not have a mounted file system, or if one of the following conditions is true:
  • The sectors to be written to are boot sectors.
  • The sectors to be written to reside outside of file system space.
  • You have explicitly locked or dismounted the volume by using FSCTL_LOCK_VOLUME or FSCTL_DISMOUNT_VOLUME.
  • The volume has no actual file system. (In other words, it has a RAW file system mounted.)
• A write on a disk handle will succeed if one of the following conditions is true:
  • The sectors to be written to do not fall within a volume’s extents.
  • The sectors to be written to fall within a mounted volume, but you have explicitly locked or dismounted the volume by using FSCTL_LOCK_VOLUME or FSCTL_DISMOUNT_VOLUME.
  • The sectors to be written to fall within a volume that has no mounted file system other than RAW.

There are strict requirements for successfully working with files opened with CreateFile using FILE_FLAG_NO_BUFFERING. For details see File Buffering.

If hFile was opened with FILE_FLAG_OVERLAPPED, the following conditions are in effect:

• The lpOverlapped parameter must point to a valid and unique OVERLAPPED structure, otherwise the function can incorrectly report that the write operation is complete.
• The lpNumberOfBytesWritten parameter should be set to NULL. To get the number of bytes written, use the GetOverlappedResult function. If the hFile parameter is associated with an I/O completion port, you can also get the number of bytes written by calling the GetQueuedCompletionStatus function.

In Windows ServerВ 2012, this function is supported by the following technologies.

Technology	Supported
Server Message Block (SMB) 3.0 protocol	Yes
SMB 3.0 Transparent Failover (TFO)	Yes
SMB 3.0 with Scale-out File Shares (SO)	Yes
Cluster Shared Volume File System (CsvFS)	Yes
Resilient File System (ReFS)	Yes

В

Synchronization and File Position

Pipes

If the pipe buffer is full when an application uses the WriteFile function to write to a pipe, the write operation may not finish immediately. The write operation will be completed when a read operation (using the ReadFile function) makes more system buffer space available for the pipe.

When writing to a non-blocking, byte-mode pipe handle with insufficient buffer space, WriteFile returns TRUE with *lpNumberOfBytesWritten —>

Windows API functions to read and write files in C

Hello, I’m playing with win API functions readFile and WriteFile.
Is it possible to open file using CreateFile in binary mode just like using fopen standard C function.
I tried with function WriteFile to write string to a file but it seems that file is opened in textual mode. What I’m trying to do is to open file in binary mode and then to write strings so that cannot be opened and examined with Notepad.

Thank you very much

6 Contributors
• forum 13 Replies 6,229 Views 5 Years Discussion Span
• comment Latest Post 10 Years Ago Latest Post by progneer.soft

Recommended Answers

There’s no way to specify the orientation of a file opened by CreateFile, it’s always binary. ReadFile and WriteFile work with raw bytes.

>What I’m trying to do is to open file in binary mode and then to write
>strings so that cannot be opened and examined with Notepad.
…

Couldn’t you just do something like this? Remeber if this sucks I am not good at the API 😉

>OPEN_ALWAYS, // existing file only
OPEN_ALWAYS creates the file if it doesn’t exist. If you want CreateFile to fail if the file doesn’t exist, use OPEN_EXISTING.

>but program ended up in an infinite loop
That’s because with the way you open the file, reaching end-of-file still returns success.

>I am not sure if writing strigs in binary mode is a good idea.
Only if you write the file with CreateFile and WriteFile, then read it using a FILE* opened with text orientation. Then it’s possible to have conversion issues depending on the contents of the strings. But as …

All 13 Replies

There’s no way to specify the orientation of a file opened by CreateFile, it’s always binary. ReadFile and WriteFile work with raw bytes.

>What I’m trying to do is to open file in binary mode and then to write
>strings so that cannot be opened and examined with Notepad.
Printable characters in the character set will always be readable by Notepad, whether you’re using binary or text orientation. If you want your strings to be unreadable, you need to encrypt them somehow rather than just write them straight to the file:

However, you can directly write numbers and other non-string data without the encryption, and it will be unrecognizable when opened with Notepad:

Thanks Narue, I understand now

please, can you check if this is a correct way of reading file:
first, file is open for both writing and reading

second I want to read contents of a file and display it on screen (I know that file contents are sentences (strings) like
«This is first sentence»
«This is second sentence»
so this is code for reading:

I had one nasty problem, At first I tried this:

but program ended up in an infinite loop (not like fwrite in C) and that way with dw_bytes_read it appears to work fine.
Can you suggest me other, better, way of doing this if this is not OK

Couldn’t you just do something like this? Remeber if this sucks I am not good at the API 😉

>OPEN_ALWAYS, // existing file only
OPEN_ALWAYS creates the file if it doesn’t exist. If you want CreateFile to fail if the file doesn’t exist, use OPEN_EXISTING.

>but program ended up in an infinite loop
That’s because with the way you open the file, reaching end-of-file still returns success.

>Can you suggest me other, better, way of doing this if this is not OK
Well, there’s nothing wrong with it, so it all boils down to style preference.

>Couldn’t you just do something like this?
Sure, but where’s the loop? 😉

What I’m trying to do is to open file in binary mode and then to write strings so that cannot be opened and examined with Notepad.

I am not sure if writing strigs in binary mode is a good idea.
Either you will end up writing the memory locations to the file, which would not be useful in the second time around when you open it or you will end up writng human readable stuff any way.

I think what you are looking for is some encrypting mechanism so that you could hide the strings from the others.

>I am not sure if writing strigs in binary mode is a good idea.
Only if you write the file with CreateFile and WriteFile, then read it using a FILE* opened with text orientation. Then it’s possible to have conversion issues depending on the contents of the strings. But as long as the file is consistently read and written as binary, there’s no problem.

>Either you will end up writing the memory locations to the file
No, you wouldn’t. WriteFile takes a pointer and writes the contents of that pointer, so the only way to get WriteFile to write the addresses is if you had an array of pointers representing the strings and passed it like this:

Thank you all for replies. Usually I do all file manipulation stuff with fopen, fwrite, fread and etc, but I wanted to know how this is done with API. Also I’ve read somewhere that C function fopen end up on CreateFile (under windows os) and that «would be wise» to use it directly to gain better performance. I don’t know if this is true, I doubt it.

yes, its true that with M$ compilers fopen and fstream eventually use win32 api functions. But there are a lot of reasons not to use win32 api for reading/writing text files and buffered i/o. Using either fstream or fgets() its really easy to read just one line of text (up to CR/LF), but win32 api its not so easy because you, the programmer, have to duplicate the functionality of fgets().

Bottom line: use win32 api directly only if speed is important to your program. Otherwise use either fstream or FILE and associated functions. Personally, I hate fstream because I think its ugly and very clumbsy. The only advantage is getline() used with std::string object. But for formatted i/o you can’t beat the ease of fprintf() and fscanf().

the easiest way is that you save the file with the extension of (.bin) instead of (.txt)

the easiest way is that you save the file with the extension of (.bin) instead of (.txt)

The file extension has nothing to do about file contents. Changing the file extension from .txt to .bin will do nothing (other than renaming the file)

extension (.bin) means that the file is in binary mode and Windows will open it in cmd (command prompt), and it can solve the problem.

And if you don’t like it.. try doing this

>>extension (.bin) means that the file is in binary mode

No it doesn’t, as the code you posted illustrates. The file extension has nothing to do with whether the file is in binary or text mode. Your own program proved it.

if you wanna see your file as you have written on it. you can use ReadFile API. it will give you the actual written data (and not the ASCII Characters).

The reason why file is not looking correct when you open it in notepad is very simple. It is because notepad is made for ASCII Charachter Set, it means that the notepad reads 2 bytes at a time and produce a ASCII character against it. so if you have written some integers or your own datatype. it’s size is changed (as int size is 4bytes) so the number you have written in the file has now been splited into two ASCII charaters.

But when you read the same file using ReadFile API, it actually reads Binary of the data that you have written and produce a charachter (or number . ) against it.

I hope you understand that.

We’re a friendly, industry-focused community of 1.20 million developers, IT pros, digital marketers, and technology enthusiasts learning and sharing knowledge.

Reach out to all the awesome people in our software development community by starting your own topic. We equally welcome both specific questions as well as open-ended discussions.