Open
Opens a disk file for reading or writing using file operations
Syntax
`
Open filename For Input [encoding_type] [lock_type] As [#]filenumber
Open filename For Output [encoding_type] [lock_type] As [#]filenumber
Open filename For Append [encoding_type] [lock_type] As [#]filenumber
Open filename For Binary [access_type] [lock_type] As [#]filenumber
Open filename For Random [access_type] [lock_type] As [#]filenumber [Len = record_length]
`
Usage
`
result = Open( filename[,] For {Input|Output|Append}[,] As filenumber )
`or`
`
result = Open( filename[,] For Binary[,] Access {Read|Write}[,] As filenumber )
or`
`
result = Open( filename[,] For Random[,] Access {Read|Write}[,] As filenumber [[,] Len = record_length] )
or`
`
Open filename For {Input|Output|Append} As filenumber
or`
`
Open filename For Binary Access {Read|Write} As filenumber
or`
`
Open filename For Random Access {Read|Write} As filenumber [Len = record_length]
Parameters
`filename`
A string value of the name of the disk file to open. Relative file paths are relative to the current directory (see `CurDir`).
`encoding_type`
The encoding to be used when reading or writing text, can be one of:

- `Encoding "ascii"` (ASCII encoding is used, default)
- `Encoding "utf8"` (8-bit Unicode encoding is used)
- `Encoding "utf16"` (16-bit Unicode encoding is used)
- `Encoding "utf32"` (32-bit Unicode encoding is used)

`access_type`
The type of access requested by the calling process.

- `Access` [`Read`] [`Write`] (both read and write access can be used, which is the default)

`lock_type`
Imposes restrictions on disk file access from other processes (threads or programs), can be either:

- `Shared` (the file can be freely accessed by other processes)
- `Lock` [`Read`] [`Write`] (both read and write access can be denied to other processes)

`filenum`
An available file number to bind to the disk file, which can be found with `FreeFile`.
`record_length`
The size, in bytes, of each record read from or written to the disk file. The default is `128`.
Return Value
In the first usage, `Open` returns zero (`0`) on success and a non-zero error code otherwise.
Description
Opens a disk file for reading and/or writing. The file number `file_num` is bound to the file on disk, for use in subsequent file operations, such as `Input #` and `Lock`. The next available file number can be retrieved with `FreeFile`.
The `Input`, `Output` and `Append` file modes open disk files for sequential text I/O, useful for reading or writing plain text files.
When the `Input` mode is specified, only reading file operations can be used, like `Line Input #` and `Get #`. If the disk file does not exist a runtime error will be thrown.
The `Append` mode specifies that only writing operations can be used, like `Print #` and `Put #`. Writing operations will take place at the end of the disk file if it exists, preserving the existing data.
The `Output` mode is like the `Append` mode, except that if the file exists then its contents are deleted and its length reset to zero before writing.
The `Input`, `Output` and `Append` file modes also allow selection of a character encoding to be used when reading from or writing text to the disk file. ASCII or a Unicode encoding may be specified (see the description of the `encoding_type` parameter above).
The `Binary` and `Random` file modes open disk files for random-access reading or writing of arbitrary sized binary data. The `Binary` file mode allows reading and writing of simple data type values, like `Byte` or `LongInt`, using binary read or write operations, like `Get #`. `LOC` and `Seek` are among the procedures used for reading and writing to arbitrary locations in the disk file. The `Random` file mode is similar to `Binary`, except that file I/O operations always use a constant data size when reading or writing.
By default, the `Binary` and `Random` file modes allow both reading and writing operations on the opened disk file, but this can be changed by specifying an access type (see the description for the `access_type` parameter above).
For any file mode, access to the opened disk file can be restricted or granted to other threads or programs by specifying a lock type (see the description for the `lock_type` parameter above). If no lock type is specified, other threads of the current program can freely open the disk file (`Shared`), while other programs cannot (`Lock Read Write`). `Lock` and `Unlock` can be used to temporarily restrict access to parts of a file.
The error code returned by `Open` can be checked using `Err` in the next line. The function version of `Open` returns directly the error code as an integer.
Example
`
' Create a string and fill it.
Dim buffer As String, f As Integer
buffer = "Hello World within a file."
' Find the first free file number.
f = FreeFile
' Open the file "file.ext" for binary usage, using the file number "f".
Open "file.ext" For Binary As #f
If Err>0 Then Print "Error opening the file":End
' Place our string inside the file, using number "f".
Put #f, , buffer
' Close all open files.
Close
' End the program. (Check the file "file.ext" upon running to see the output.)
End
`
`
'OPEN A COM PORT
Open Com "COM1:9600,N,8,1" As #1
If Err>0 Then Print "The port could not be opened."
'COM1, 9600 BAUD, NO PARITY BIT, EIGHT DATA BITS, ONE STOP BIT
`
`
'function version of OPEN
If Open("file.ext" For Binary Access Read As #1) = 0 Then
Print "Successfully opened file"
'' ...
Close #1
Else
Print "Error opening file"
End If
`
Platform Differences

- Linux requires the `filename` case matches the real name of the file. Windows and DOS are case insensitive.
- Path separators in Linux are forward slashes `/`. Windows uses backward slashes `\` but it allows for forward slashes `/`. DOS uses backward slashes `\`.
- On Windows, a file number used in a dynamic link library is not the same as an identical file number used in the main program. File numbers can not be passed or returned and then used between a DLL and an executable.
- If you try to open a directory on Linux, the `Open` command will succeed.

Differences from QB

- Using MS-DOS device names to open streams or hardware devices (`"LPT:"`, `"SCR:"`, etc.) is supported only in the -lang qb dialect; for other modes FreeBASIC's new composite keywords must be used: see `Open Com`, `Open Cons`, `Open Err`, `Open Pipe`, `Open Lpt`, `Open Scrn`.
- `Open` can be called as a function that returns an error code.

Dialect Differences

- The -lang qb dialect supports the old GW-BASIC-style syntax `OPEN mode_string, #filenum, filename [length]` with mode_string being `"I"` for input, `"O"` for output, `"A"` for append, `"R"` for random, `"B"` for binary.

See also

- `Err` (and a list of error codes)
- `Close`
- `FreeFile`
- `Open Cons`, `Open Err`, `Open Pipe`, `Open Lpt`, `Open Com`, `Open Scrn`