Windows API Reference

Documentation for Windows Operating System Components

Win32 File I/O

This section covers the Win32 API functions for performing file input and output operations on the Windows operating system. These functions allow applications to create, read, write, and manage files and directories.

Core Concepts

Key Functions

Creating and Opening Files

Reading from Files

Writing to Files

File Management

CreateFile

Creates or opens a file or I/O device (such as a disk drive, partition, or communications resource).

HANDLE CreateFile(
  LPCTSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
);

Parameters

Name Type Description
lpFileName LPCTSTR The name of the file or device.
dwDesiredAccess DWORD The generic access rights to the file.
dwShareMode DWORD The mode in which the file may be shared.
lpSecurityAttributes LPSECURITY_ATTRIBUTES A pointer to a SECURITY_ATTRIBUTES structure.
dwCreationDisposition DWORD Determines the action to take if the file exists or does not exist.
dwFlagsAndAttributes DWORD File attributes and flags.
hTemplateFile HANDLE A handle to a template file with the desired attributes.

Return Value

If the function succeeds, the return value is an open handle to the specified file or device. If the function fails, the return value is INVALID_HANDLE_VALUE.

Remarks

  • Use CloseHandle to close the handle when you are finished with it.
  • The behavior of this function can be affected by the lpSecurityAttributes parameter.

See Also

ReadFile

Reads data from a file or I/O device. Works with files opened with both synchronous and overlapped access.

BOOL ReadFile(
  HANDLE       hFile,
  LPVOID       lpBuffer,
  DWORD        nNumberOfBytesToRead,
  LPDWORD      lpNumberOfBytesRead,
  LPOVERLAPPED lpOverlapped
);

Parameters

Name Type Description
hFile HANDLE A handle to the file or device for which read information is requested.
lpBuffer LPVOID A pointer to the buffer that receives the data read from the file.
nNumberOfBytesToRead DWORD The maximum number of bytes to be read.
lpNumberOfBytesRead LPDWORD A pointer to a variable that receives the number of bytes actually read.
lpOverlapped LPOVERLAPPED A pointer to an OVERLAPPED structure.

Return Value

If the function succeeds, and the dwNumberOfBytesToRead parameter is non-zero, the return value is TRUE. If the function succeeds, and dwNumberOfBytesToRead is zero, the return value is TRUE and lpNumberOfBytesRead is zero. If the function fails, the return value is FALSE.

Remarks

  • If lpOverlapped is NULL, the function returns immediately after reading the specified number of bytes into the buffer.
  • If lpOverlapped is not NULL, the function may return before the read operation is complete (asynchronous operation).

See Also

WriteFile

Writes data to a file or I/O device. Works with files opened with both synchronous and overlapped access.

BOOL WriteFile(
  HANDLE       hFile,
  LPCVOID      lpBuffer,
  DWORD        nNumberOfBytesToWrite,
  LPDWORD      lpNumberOfBytesWritten,
  LPOVERLAPPED lpOverlapped
);

Parameters

Name Type Description
hFile HANDLE A handle to the file or device. The handle must have been created with the GENERIC_WRITE access right.
lpBuffer LPCVOID A pointer to the buffer containing the data to be written.
nNumberOfBytesToWrite DWORD The number of bytes to write to the file.
lpNumberOfBytesWritten LPDWORD A pointer to a variable that receives the number of bytes actually written.
lpOverlapped LPOVERLAPPED A pointer to an OVERLAPPED structure.

Return Value

If the function succeeds, and the nNumberOfBytesToWrite parameter is non-zero, the return value is TRUE. If the function succeeds, and nNumberOfBytesToWrite is zero, the return value is TRUE and lpNumberOfBytesWritten is zero. If the function fails, the return value is FALSE.

Remarks

  • If lpOverlapped is NULL, the function returns immediately after writing the specified number of bytes from the buffer.
  • If lpOverlapped is not NULL, the function may return before the write operation is complete (asynchronous operation).

See Also

SetFilePointer

Moves the file pointer of the specified file to a location within the file.

DWORD SetFilePointer(
  HANDLE  hFile,
  LONG    lDistanceToMove,
  PLONG   lpDistanceToMoveHigh,
  DWORD   dwMoveMethod
);

Parameters

Name Type Description
hFile HANDLE A handle to the file.
lDistanceToMove LONG The number of bytes to move the file pointer.
lpDistanceToMoveHigh PLONG A pointer to the high-order 32 bits of the number of bytes to move the file pointer.
dwMoveMethod DWORD The starting point for the move.

Return Value

If the function succeeds, the return value is the new value of the file pointer. If the function fails, the return value is INVALID_SET_FILE_POINTER.

Remarks

  • Use SetFilePointerEx for 64-bit file pointer support.
  • The dwMoveMethod parameter can be one of the following: FILE_BEGIN, FILE_CURRENT, or FILE_END.

See Also

CloseHandle

Closes an open object handle.

BOOL CloseHandle(
  HANDLE hObject
);

Parameters

Name Type Description
hObject HANDLE A handle to an open object.

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks

  • This function is essential for releasing system resources associated with a handle.
  • Always close handles when they are no longer needed to prevent resource leaks.

See Also

Back to Top