{{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)//
	##//filenum//##
		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 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 ##[[KeyPgLineinput 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).

	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 an integer.

{{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]]##.
	- ##**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, #filenum, 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]]##

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