GET (File I/O)

• Source: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgGetfileio
• Last revised: 2025-06-01

---

Reads data from a file to a buffer

Syntax

Get #filenum As Long, [position As longint], ByRef data As Any [, [amount As Uinteger] [, ByRef bytesread As Uinteger] ]
Get #filenum As Long, [position As longint], data As String [, , ByRef bytesread As Uinteger ]
Get #filenum As Long, [position As longint], data() As Any [, , ByRef bytesread As Uinteger ]

Usage

Get #filenum, position, data [, [amount] [, bytesread ] ]
varres = Get (#filenum, position, data [, [amount] [, bytesread ] ] )

Parameters

filenum

The value passed to Open when the file was opened.

position

The position where the read must start. If the file was opened 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 (including referenced by This), or a dereferenced pointer. The read operation will try to fill completely the variable, unless the EOF is reached. For a user-defined type instance, the data impacted is only the non-static data members.

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 Strings, 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 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 * 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.

Return Value

Get() returns a 32 bit Long: a zero (0) on success; non-zero on error.

Note: if 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.

Description

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 Random mode, the size in bytes of the data to read must match the specified record size.

*Note:

• If a real [w/z]string variable is passed to Get, the amount parameter should be forbidden as it is when passing a string. Do not use. Otherwise, it is ignored (except for the '0' value).

• If a dereferenced [w/z]string pointer is passed to Get, the amount parameter is not taken into account as it is when passing a dereferenced numeric pointer. Do not use. But instead of respecting the amount parameter, the pointed buffer must begin with at least as many non-zero elements as the number of elements to read.

• For finer granularity, any [w/z]string variable can be safely passed to Get as a numeric buffer by providing the first numeric element (an indexed [w/z]string variable, or a dereferenced [w/z]string pointer then indexed) and the number of numeric elements to be processed.*

Note:

• Using Get # is naturally dedicated to Binary/Random Access file mode.

• It is also allowed in Input Access file mode, but this was never well tested and results may vary.