Atari ST series Technical Reference Manual page 127

where fname is a pointer to the null-terminated ASCII filen­
ame of the file to open, and mode is a flag that specifies
which operations will be available once the file has been
opened. Possible values for mode include:
Mode
Number Operations
0 Read only
2 Write only
3 Read or write
If the file can be opened, a file handle is returned in han­
dle. If it can't be opened (for instance, if GEMDOS can't find
some element of the path name), the appropriate GEMDOS
error number will be returned. For a complete list of GEM­
DOS errors, see Appendix D.
Once a file has been opened for reading and/or writing,
it's possible to read the contents of that file by using the
Fread() function:
long status, count;
int handle;
char ^buffer;
status = Fread(handle, count, buffer);
This function reads count number of bytes from the file
whose file handle is stored in handle, and places that data
into the buffer whose address is stored in buffer. If the func­
tion is successful, the actual number of bytes read is returned
in status. If the function attempts to read past the end of the
file, a 0 is returned. For any other error, a negative GEMDOS
error number is returned (see Appendix D).
Unless otherwise specified, file reads and writes start at
the beginning of the file and progress sequentially towards
the end of the file. Let's say, for example, that you open a
file that's 1000 bytes long for reading. The internal file
pointer of GEMDOS, which keeps track of where you are in
a file, is initially set at the beginning of the file, so the first
time you call Fread() to read 100 bytes, you'll get the first
100 bytes in the file. After you read that 100 bytes, the file
pointer is moved to the end of the block that you read. The
next time you read 100 bytes, therefore, you'll get the second
100, and so on until you reach the end of the file. Since disks
are basically random-access devices, however, you're not
confined to reading files in order. You can move the file
GEMDOS File System Functions