# FileOpen [AHK_L 42+]

Opens a file.

    file := FileOpen(Filename, Flags [, Encoding])

### Parameters

Filename | The path of the file to open, which is assumed to be in A_WorkingDir if an absolute path isn't specified.
Flags | Either [in AHK_L 54+] a string of characters indicating the desired access mode followed by other options (with optional spaces or tabs in between); or [in AHK_L 42+] a combination (sum) of numeric flags. Supported values are described in the table below.
Encoding | The code page to use for text I/O if the file does not contain a UTF-8 or UTF-16 byte order mark. If omitted, the current value of A_FileEncoding is used.

### Flags

|  | Access modes (mutually-exclusive)
--- | --- | ---
r | 0 | Read: Fails if the file doesn't exist.
w | 1 | Write: Creates a new file, overwriting any existing file.
a | 2 | Append: Creates a new file if the file didn't exist, otherwise moves the file pointer to the end of the file.
rw | 3 | Read/Write: Creates a new file if the file didn't exist.
h |  | Indicates that Filename is a file handle to wrap in an object. Sharing mode flags are ignored. The file handle is not closed automatically when the file object is destroyed and calling Close has no effect. Note that Seek, Tell and Length should not be used if Filename is a handle to a nonseeking device such as a pipe or a communications device.
|  | Sharing mode flags
-rwd |  | Locks the file for read, write and/or delete access. Any combination of `r`, `w` and `d` may be used. Specifying `-` is the same as specifying `-rwd`. If omitted entirely, the default is to share all access.
| 0 | If Flags is numeric, the absence of sharing mode flags causes the file to be locked.
| 0x100 | Shares read access.
| 0x200 | Shares write access.
| 0x400 | Shares delete access.
|  | End of line (EOL) options
``n` | 4 | Replace ``r`n` with ``n` when reading and ``n` with ``r`n` when writing.
``r` | 8 | Replace standalone ``r` with ``n` when reading.

### Return Value

If the file is opened successfully, the return value is a File object.

If the function fails, the return value is 0 and [in AHK_L 54+] A_LastError contains an error code.

Use `if file` or `IsObject(file)` to check if the function succeeded.

### Remarks

When a UTF-8 or UTF-16 file is created, a byte order mark is written to the file unless Encoding (or A_FileEncoding if Encoding is omitted) contains "UTF-8-RAW" or "UTF-16-RAW".

When a file containing a UTF-8 or UTF-16 byte order mark (BOM) is opened with read access, the BOM is excluded from the output by positioning the file pointer after it. Therefore, `File.Position` may report 3 or 2 immediately after opening the file.

### Related

FileEncoding, File Object, FileRead

### Examples

    ; Example: This is a working script that writes some text to a file then reads it back into memory.
    ; It provides the same functionality as this DllCall-example.

    FileSelectFile, FileName, S16,, Create a new file:
    if (FileName = "")
    	return
    file := FileOpen(FileName, "w")
    if !IsObject(file)
    {
    	MsgBox Can't open "%FileName%" for writing.
    	return
    }
    TestString := "This is a test string.`r`n"  ; When writing a file this way, use `r`n rather than `n to start a new line.
    file.Write(TestString)
    file.Close()

    ; Now that the file was written, read its contents back into memory.
    file := FileOpen(FileName, "r-d") ; read the file ("r"), share all access except for delete ("-d")
    if !IsObject(file)
    {
    	MsgBox Can't open "%FileName%" for reading.
    	return
    }
    CharsToRead := StrLen(TestString)
    TestString := file.Read(CharsToRead)
    file.Close()
    MsgBox The following string was read from the file: %TestString%

    ; Open the script in read-only mode and read its first line:
    file := FileOpen(A_ScriptFullPath, "r")
    MsgBox % file.ReadLine()

    ; Open a console window for this demonstration:
    DllCall("AllocConsole")
    ; Open the application's stdin/stdout handles in newline-translated mode.
    stdin  := FileOpen(DllCall("GetStdHandle", "int", -10, "ptr"), "h `n")
    stdout := FileOpen(DllCall("GetStdHandle", "int", -11, "ptr"), "h `n")
    stdout.Write("Enter your query.`n\> ")
    stdout.Read(0) ; Flush the write buffer.
    query := RTrim(stdin.ReadLine(), "`n")
    stdout.WriteLine("Your query was '" query "'. Have a nice day.")
    stdout.Read(0) ; Flush the write buffer.
    Sleep 5000