{{fbdoc item="title" value="OPEN"}}----
Opens a disk file for reading or writing using file operations

{{fbdoc item="syntax"}}##
	**Open** //filename// **For** **[[KeyPgInputfilemode|Input]]** [//encoding_type//] [//lock_type//] **As** [**#**]//filenumber//
	**Open** //filename// **For** **[[KeyPgOutput|Output]]** [//encoding_type//] [//lock_type//] **As** [**#**]//filenumber//
	**Open** //filename// **For** **[[KeyPgAppend|Append]]** [//encoding_type//] [//lock_type//] **As** [**#**]//filenumber//
	
	**Open** //filename// **For** **[[KeyPgBinary|Binary]]** [//access_type//] [//lock_type//] **As** [**#**]//filenumber//
	**Open** //filename// **For** **[[KeyPgRandom|Random]]** [//access_type//] [//lock_type//] **As** [**#**]//filenumber// [**Len =** //record_length//]
##
{{fbdoc item="usage"}}##
	//result// = **Open**( //filename//[,] **For** {**[[KeyPgInputfilemode|Input]]**|**[[KeyPgOutput|Output]]**|**[[KeyPgAppend|Append]]**}[,] **As** //filenumber// )
		##//or//##
	//result// = **Open**( //filename//[,] **For** **[[KeyPgBinary|Binary]]**[,] **[[KeyPgAccess|Access]]** {**Read**|**Write**}[,] **As** //filenumber// )
		##//or//##
	//result// = **Open**( //filename//[,] **For** **[[KeyPgRandom|Random]]**[,] **[[KeyPgAccess|Access]]** {**Read**|**Write**}[,] **As** //filenumber// [[,] **Len = ** //record_length//] )
		##//or//##
	**Open** //filename// **For** {**[[KeyPgInputfilemode|Input]]**|**[[KeyPgOutput|Output]]**|**[[KeyPgAppend|Append]]**} **As** //filenumber//
		##//or//##
	**Open** //filename// **For** **[[KeyPgBinary|Binary]]** **[[KeyPgAccess|Access]]** {**Read**|**Write**} **As** //filenumber//
		##//or//##
	**Open** //filename// **For** **[[KeyPgRandom|Random]]** **[[KeyPgAccess|Access]]** {**Read**|**Write**} **As** //filenumber// [**Len = ** //record_length//]

##
{{fbdoc item="param"}}
	##//filename//##
		A string value of the name of the disk file to open. Relative file paths are relative to the current directory (see ##[[KeyPgCurdir|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)//
	##//filenumber//##
		An available file number to bind to the disk file, which can be found with ##[[KeyPgFreefile|Freefile]]##.
	##//record_length//##
		The size, in bytes, of each record read from or written to the disk file. The default is ##128##.

{{fbdoc item="ret"}}
	In the first usage, ##**Open()**## returns a 32 bit ##[[KeyPgLong|Long]]## value: zero (##0##) on success and a non-zero error code otherwise.

{{fbdoc item="desc"}}
	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 ##[[KeyPgInputPp|Input #]]## and ##[[KeyPgLock|Lock]]##. The next available file number can be retrieved with ##[[KeyPgFreefile|Freefile]]##.
	
	The ##[[KeyPgInputfilemode|Input]]##, ##[[KeyPgOutput|Output]]## and ##[[KeyPgAppend|Append]]## file modes open disk files for sequential text I/O, useful for reading or writing plain text files:
		- When the ##[[KeyPgInputfilemode|Input]]## mode is specified, only reading file operations can be used, like ##[[KeyPgLineinputPp|Line Input #]]## and ##[[KeyPgGetfileio|Get #]]##. If the disk file does not exist a runtime error will be thrown.
		- The ##[[KeyPgAppend|Append]]## mode specifies that only writing operations can be used, like ##[[KeyPgPrintPp|Print #]]## and ##[[KeyPgPutfileio|Put #]]##.  Writing operations will take place at the end of the disk file if it exists, preserving the existing data.
		- The ##[[KeyPgOutput|Output]]## mode is like the ##[[KeyPgAppend|Append]]## mode, except that if the file exists then its contents are deleted and its length reset to zero before writing.
	
	The ##[[KeyPgInputfilemode|Input]]##, ##[[KeyPgOutput|Output]]## and ##[[KeyPgAppend|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 ##[[KeyPgBinary|Binary]]## and ##[[KeyPgRandom|Random]]## file modes open disk files for random-access reading or writing of arbitrary sized binary data:
		- The ##[[KeyPgBinary|Binary]]## file mode allows reading and writing of simple data type values, like ##[[KeyPgByte|Byte]]## or ##[[KeyPgLongint|Longint]]##, using binary read or write operations, like ##[[KeyPgGetfileio|Get #]]##. ##[[KeyPgLoc|Loc]]## and ##[[KeyPgSeekreturn|Seek]]## are among the procedures used for reading and writing to arbitrary locations in the disk file.
		- The ##[[KeyPgRandom|Random]]## file mode is similar to ##[[KeyPgBinary|Binary]]##, except that file I/O operations always use a constant data size when reading or writing.
	
	By default, the ##[[KeyPgBinary|Binary]]## and ##[[KeyPgRandom|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). When opening an existing file in ##[[KeyPgBinary|Binary]]## or ##[[KeyPgRandom|Random]]## file mode, and with the only ##Write## access type specified, all data in the file are previously deleted at opening, before any other operation.
	
	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##). ##[[KeyPgLock|Lock]]## and ##[[KeyPgUnlock|Unlock]]## can be used to temporarily restrict access to parts of a file.
	
	The error code returned by ##**Open**##  can be checked using ##[[KeyPgErr|Err]]## in the next line. The function version of  ##**Open**## returns directly the error code as a 32 bit ##[[KeyPgLong|Long]]##.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/fileio/open.bas"}}%%(freebasic)
' 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
%%

{{fbdoc item="filename" value="examples/manual/fileio/opencom.bas"}}%%(freebasic)
'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
%%
{{fbdoc item="filename" value="examples/manual/fileio/openfunc.bas"}}%%(freebasic)
'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
%%

{{fbdoc item="target"}}
	- 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.

{{fbdoc item="diff"}}
	- Using MS-DOS device names to open streams or hardware devices (##"LPT:"##, ##"SCR:"##, etc.) is supported only in the //[[CompilerOptlang|-lang qb]]// dialect; for other modes ""FreeBASIC's"" new composite keywords must be used: see ##[[KeyPgOpenCom|Open Com]]##,  ##[[KeyPgOpenCons|Open Cons]]##,  ##[[KeyPgOpenErr|Open Err]]##,  ##[[KeyPgOpenPipe|Open Pipe]]##,  ##[[KeyPgOpenLpt|Open Lpt]]##,  ##[[KeyPgOpenScrn|Open Scrn]]##, ##[[KeyPgOpenTcp|Open Tcp]]##, and ##[[KeyPgOpenTcpServer|Open Tcp Server]]##.
	- ##**Open**## can be called as a function that returns an error code.

{{fbdoc item="lang"}}
	- The //[[CompilerOptlang|-lang qb]]// dialect supports the old GW-BASIC-style syntax ##OPEN mode_string, #filenumber, filename [length]## with mode_string being ##"I"## for input, ##"O"## for output, ##"A"## for append, ##"R"## for random, ##"B"## for binary. 

{{fbdoc item="see"}}
	- ##[[KeyPgErr|Err]]## (and [[TblRuntimeErrors|a list of error codes]])
	- ##[[KeyPgClose|Close]]##
	- ##[[KeyPgFreefile|Freefile]]##
	- ##[[KeyPgOpenCons|Open Cons]]##, ##[[KeyPgOpenErr|Open Err]]##, ##[[KeyPgOpenPipe|Open Pipe]]##, ##[[KeyPgOpenLpt|Open Lpt]]##, ##[[KeyPgOpenCom|Open Com]]##, ##[[KeyPgOpenScrn|Open Scrn]]##, ##[[KeyPgOpenTcp|Open Tcp]]##, ##[[KeyPgOpenTcpServer|Open Tcp Server]]##

{{fbdoc item="back" value="CatPgFile|File I/O Functions"}}
