Function Reference

FileOpen

Opens a file for reading or writing.

FileOpen ( "filename" [, mode = 0] )

Parameters

filename Filename of the file to open.

mode [optional] Mode to open the file in.
Can be a combination of the following:
$FO_READ (0) = Read mode (default)
$FO_APPEND (1) = Write mode (append to end of file)
$FO_OVERWRITE (2) = Write mode (erase previous contents)
$FO_CREATEPATH (8) = Create directory structure if it doesn't exist (See Remarks).
$FO_BINARY (16) = Force binary mode (See Remarks).
$FO_UNICODE or $FO_UTF16_LE (32) = Use Unicode UTF16 Little Endian reading and writing mode.
$FO_UTF16_BE (64) = Use Unicode UTF16 Big Endian reading and writing mode.
$FO_UTF8 (128) = Use Unicode UTF8 (with BOM) reading and writing mode.
$FO_UTF8_NOBOM (256) = Use Unicode UTF8 (without BOM) reading and writing mode.
$FO_ANSI (512) = Use ANSI reading and writing mode.
$FO_UTF16_LE_NOBOM (1024) = Use Unicode UTF16 Little Endian (without BOM) reading and writing mode.
$FO_UTF16_BE_NOBOM (2048) = Use Unicode UTF16 Big Endian (without BOM) reading and writing mode.
$FO_FULLFILE_DETECT (16384) = When opening for reading and no BOM is present, use the entire file to determine if it is UTF8 or UTF16. If this is not used then only the initial part of the file (up to 64KB) is checked for performance reasons.
The folder path must already exist (except using $FO_CREATEPATH mode - See Remarks).

Constants are defined in FileConstants.au3.

Return Value

Success: a file "handle" for use with subsequent file functions.

Failure: -1 if error occurs.

Remarks

The file handle must be closed with the FileClose() function.

A file may fail to open due to access rights or attributes.

The default mode when writing text is UTF8 (without BOM) - use the unicode mode flags to change this. When reading without an explicit unicode mode flag, the content of the file is examined and a guess is made whether the file is UTF8, UTF16 or ANSI. If opening an existing file and that file has a BOM then the BOM will be honored regardless of the unicode mode flags passed.

Opening a file in write mode creates the file if it does not exist. Directories are not created unless the correct flag is used.

When reading and writing via the same file handle, the FileSetPos() function must be used to update the current file position.

A file can be read as binary (byte) data by using FileOpen() with the binary flag.

See "Unicode Support" for a detailed description.

FileClose, FileFlush, FileGetPos, FileRead, FileReadLine, FileSetPos, FileWrite, FileWriteLine

Example

Example 1

#include <FileConstants.au3>
#include <MsgBoxConstants.au3>
#include <WinAPIFiles.au3>
Example()
Func  Example()
; Create a constant variable in Local scope of the filepath that will be read/written to.
Local Const $sFilePath= _WinAPI_GetTempFileName (@TempDir )
; Create a temporary file to read data from.
If Not FileWrite ($sFilePath,"This is an example of using FileOpen.")Then
MsgBox ($MB_SYSTEMMODAL,"","An error occurred whilst writing the temporary file.")
Return False
EndIf
; Open the file for reading and store the handle to a variable.
Local $hFileOpen= FileOpen ($sFilePath,$FO_READ)
If $hFileOpen= - 1Then
MsgBox ($MB_SYSTEMMODAL,"","An error occurred when reading the file.")
Return False
EndIf
; Read the contents of the file using the handle returned by FileOpen.
Local $sFileRead= FileRead ($hFileOpen)
; Close the handle returned by FileOpen.
FileClose ($hFileOpen)
; Display the contents of the file.
MsgBox ($MB_SYSTEMMODAL,"","Contents of the file:"&@CRLF &$sFileRead)
; Delete the temporary file.
FileDelete ($sFilePath)
EndFunc ;==>Example

Example 2

#include <FileConstants.au3>
#include <MsgBoxConstants.au3>
#include <WinAPIFiles.au3>
Example()
Func  Example()
; Create a constant variable in Local scope of the filepath that will be read/written to.
Local Const $sFilePath= _WinAPI_GetTempFileName (@TempDir )
; Open the file for read/write access.
Local $hFileOpen= FileOpen ($sFilePath,$FO_READ+ $FO_OVERWRITE)
If $hFileOpen= - 1Then
MsgBox ($MB_SYSTEMMODAL,"","An error occurred when reading/writing the file.")
Return False
EndIf
; Write some data.
FileWrite ($hFileOpen,"This is some data to show that the handle was open with read/write access."&@CRLF )
; Retrieve the current position in the file.
Local $iFilePos= FileGetPos ($hFileOpen)
; Now, adjust the position to the beginning.
FileSetPos ($hFileOpen,0,$FILE_BEGIN)
; Display the contents of the file.
MsgBox ($MB_SYSTEMMODAL,"",FileRead ($hFileOpen))
; Now, adjust the position back to the previous position.
FileSetPos ($hFileOpen,0,$iFilePos)
; Write some addition data.
FileWrite ($hFileOpen,"This is some additional data.")
; Adjust the position back to the previous position.
FileSetPos ($hFileOpen,0,$FILE_BEGIN)
; Display the contents of the file.
MsgBox ($MB_SYSTEMMODAL,"",FileRead ($hFileOpen))
; Close the handle returned by FileOpen.
FileClose ($hFileOpen)
; Delete the temporary file.
FileDelete ($sFilePath)
Return True
EndFunc ;==>Example