{{fbdoc item="title" value="GET (File I/O)"}}----
Reads data from a file to a buffer

{{fbdoc item="syntax"}}##
	**Get** #//filenum// [[KeyPgAs As]] [[KeyPgLong Long]], [//position// [[KeyPgAs As]] [[KeyPgLongint longint]]], [[KeyPgByref ByRef]] //data// [[KeyPgAs As]] [[KeyPgAny Any]] [, [//amount// [[KeyPgAs As]] [[KeyPgUinteger Uinteger]]] [, [[KeyPgByref ByRef]] //bytesread// [[KeyPgAs As]] [[KeyPgUinteger Uinteger]]] ]
	**Get** #//filenum// [[KeyPgAs As]] [[KeyPgLong Long]], [//position// [[KeyPgAs As]] [[KeyPgLongint longint]]], //data// [[KeyPgAs As]] [[KeyPgString String]] [, , [[KeyPgByref ByRef]] //bytesread// [[KeyPgAs As]] [[KeyPgUinteger Uinteger]] ]
	**Get** #//filenum// [[KeyPgAs As]] [[KeyPgLong Long]], [//position// [[KeyPgAs As]] [[KeyPgLongint longint]]], //data()// [[KeyPgAs As]] [[KeyPgAny Any]] [, , [[KeyPgByref ByRef]] //bytesread// [[KeyPgAs As]] [[KeyPgUinteger Uinteger]] ]
##
{{fbdoc item="usage"}}##
	**Get** #//filenum//, //position//, //data// [, [//amount//] [, //bytesread// ] ]
	varres = **Get** (#//filenum//, //position//, //data// [, [//amount//] [, //bytesread// ] ] )
##
{{fbdoc item="param"}}
	##//filenum//##
		The value passed to ##[[KeyPgOpen Open]]## when the file was opened.
	##//position//##
		The position where the read must start. If the file was opened ##[[KeyPgRandom For Random]]##, the position is in records; otherwise, it is in bytes. If omitted, reading starts at the present file pointer position.  The position is 1-based: i.e. first record or byte of a file is at position ##1##.
		If ##//position//## is omitted or zero (##0##), file reading will start from the current file position.
	##//data//##
		The buffer where data is written. It can be a numeric variable, a string, an array, a user defined type or a dereferenced pointer. The read operation will try to fill completely the variable, unless the ##[[KeyPgEof EOF]]## is reached.
		When getting arrays, ##//data//## should be followed by an empty pair of brackets: "##()##".  ##**Get**## will read data for all of the values in the array.  ##//amount//## is not allowed.
		When getting ##[[KeyPgString String]]##s, the number of bytes read is the same as the number of bytes in the string data. ##//amount//## is not allowed.
		Note: If you want to read values into a buffer, you should NOT pass a pointer to the buffer; instead you should pass the first variable in the buffer. (This can be done by dereferencing the pointer with ##[[KeyPgOpValueOf Operator * (Value of)]]##.) If you pass a pointer directly, then ##**Get**## will overwrite the pointer variable, not the memory it points to.
	##//amount//##
		Makes ##**Get**## read ##//amount//## consecutive variables from file to memory, i.e. it reads ##(//amount// * [[KeyPgSizeof Sizeof]](//data//) )## bytes of data from file into the memory starting at ##//data//##'s memory location.  If ##//amount//## is omitted it defaults to ##1##, meaning that ##**Get**## just reads a single variable.
	##//bytesread//##
		An unsigned integer variable to accept the result of the number of bytes read successfully from the file.

{{fbdoc item="ret"}}
	Zero (##0##) on success; non-zero on error. Note: if ##[[KeyPgEof EOF]]## (end of file) is reached while reading, ##**Get**## will return success.  The amount of bytes actually read can be checked by passing a ##//bytesread//## variable.

{{fbdoc item="desc"}}
	Reads binary data from a file to a buffer variable

	##**Get**## can be used as a function, and will return ##0## on success or an error code on failure.	

	For files opened in ##[[KeyPgRandom Random]]## mode, the size in bytes of the data to read must match the specified record size.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/fileio/get.bas"}}%%(freebasic)
dim shared f as integer

sub get_integer()

	dim buffer as integer ' Integer variable

	' Read an Integer (4 bytes) from the file into buffer, using file number "f".
	get #f, , buffer

	' print out result
	print buffer
	print

end sub

sub get_array()

	dim an_array(0 to 10-1) as integer ' array of Integers

	' Read 10 Integers (10 * 4 = 40 bytes) from the file into an_array, using file number "f".
	get #f, , an_array()

	' print out result
	for i as integer = 0 to 10-1
	    print an_array(i)
	next
	print

end sub

sub get_mem

	dim pmem as integer ptr

	' allocate memory for 5 Integers
	pmem = allocate(5 * sizeof(integer))

	' Read 5 integers (5 * 4 = 20 bytes) from the file into allocated memory
	get #f, , *pmem, 5 ' Note pmem must be dereferenced (*pmem, or pmem[0])

	' print out result using [] Pointer Indexing
	for i as integer = 0 to 5-1
	    print pmem[i]
	next
	print

	' free pointer memory to prevent memory leak
	deallocate pmem

end sub

' Find the first free file file number.
f = freefile

' Open the file "file.ext" for binary usage, using the file number "f".
open "file.ext" for binary as #f

  get_integer()

  get_array()

  get_mem()

' Close the file.  
close #f
%%

{{fbdoc item="filename" value="examples/manual/fileio/get-file.bas"}}%%(freebasic)
' Load a small text file to a string

Function LoadFile(byref filename As string) As String
	
	Dim h As Integer
	Dim txt As String
	
	h = FreeFile
	
	if Open( filename For Binary Access Read As #h ) <> 0 then return ""
	
	If Lof(h) > 0 Then
	    
	    txt = String(Lof(h), 0)
	    if Get( #h, ,txt ) <> 0 then txt = ""
	    
	End If
	
	Close #h
	
	Return txt
	
End Function

Dim ExampleStr As String
ExampleStr = LoadFile("smallfile.txt")
Print ExampleStr
%%

{{fbdoc item="diff"}}
	- ##**Get**## in FB can read full arrays as in VB or, alternatively, read a multiple of the data size into the memory.
	- ##**Get**## can be used as a function in FB, to find the success/error code returned without having to use error handling procedures.
	- FB allows the ##//bytesread//## parameter, to check how many bytes have been successfully read in.

{{fbdoc item="see"}}
	- ##[[KeyPgGetgraphics Get (Graphics)]]## different usage of same keyword 
	- ##[[KeyPgPutfileio Put (File I/O)]]##
	- ##[[KeyPgOpen Open]]##
	- ##[[KeyPgClose Close]]##
	- ##[[KeyPgBinary Binary]]##
	- ##[[KeyPgRandom Random]]##
	- ##[[KeyPgFreefile Freefile]]##
	- ##[[ProPgFileIO File I/O methods comparison]]##

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