FGets

Reads a line from the specified input (buffered) (V36)

This function reads in a single line from the specified input stopping at a newline (line feed, ASCII code 10) character or EOF. In either event, UP TO the number of len specified bytes minus 1 will be copied into the buffer. If a length of 50 is passed and the input line is longer than 49 bytes, it will return 49 characters. It returns the buffer pointer normally, or NULL if EOF is the first thing read.

If terminated by a newline, the newline WILL be the last character in the buffer. This is a buffered read operation. The string read in IS null-terminated.

See the BUGS section for the conditions under which the string is never null-terminated.

fh

FileHandle to use for buffered I/O

buf

Area to read bytes into.

len

Number of bytes to read, must be > 0.

buffer

Pointer to buffer passed in, or NULL for immediate EOF or for an error. If NULL is returned for an EOF, IoErr() will return 0. Otherwise, an error has occured.

The AmigaDOS FGets() function is patterned after the 'C' standard I/O function fgets() but there is a crucial difference which can produce buffer overflows: FGets() uses an unsigned length parameter whereas fgets() uses a signed integer. If you accidentally pass a negative length to fgets() it will stop immediately. But if you do the same with FGets(), the length will be interpreted as a very large unsigned number. This may lead to a string buffer overflow which could corrupt data and lead to undefined behaviour.

In V36 and V37, it copies one more byte than it should if it doesn't hit an EOF or newline. In the example above, it would copy 50 bytes and put a null in the 51st. This is fixed in dos.library V39. Workaround for V36/V37: pass in buffersize-1.

The dos.library V39 fix for the buffer overflow has a side effect in that if you accidentally pass length=0 then FGets() will effectively use a buffer size of 4294967295 characters. Regardless of its size, your buffer may be subject to overflow if this occurs. Buffer overflows can corrupt data and lead to undefined behaviour.

This is fixed in dos.library 47.27. Passing length=0 will make FGets() return NULL with IoErr() returning 0, indicating an EOF condition. Nothing will be written to the buffer. No null-termination will be provided for a buffer of size 0.

FRead(), FPuts(), FGetC()