FILES LIBRARY
A Programming Language Manual




fopen
( lib: Files, file: ../src/gs/gslib_files.cpp )
ptr fopen( filename, mode )

IN
str filename path to the file to be opened
int mode open mode 0=read, 1=write, 2=both
OUT
ptr file handler

Opens the file with the path and name specified by the filename parameter.
If mode is 0 then the file will be opened only for read. File must exist.
If mode is 1 then the file will be opened only for write. If not found, the file is created, otherwise it's content will cleared.
If mode is 2 then the file will be opened for both read and write. If not found, the file is created. Useful for appending new data.
If the open is successful, the file handler is returned. If not, it will return an invalid ptr (NULL).
The directories from the specified file path must always exist.
Remember that to specify the backslash in file paths, you must use a double backslash (like "c:\\myfile.txt")
The file cursor is the current position inside the file (in bytes), where the next read or write will take place.
When a file is opened, it's file cursor is set from the beginning of the file (0).
Always remeber to finaly close opened files, with gs_fileclose.




 C/C++ source code


fsize
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fsize( f )

IN
ptr f file handler
OUT
int file's size

Returns the file's size in bytes
See gs_fopen for examples.


 C/C++ source code


fseek
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fseek( f, pos, mode )

IN
ptr f file handler
int pos position to seek to
int mode seek mode 0=beginning, 1=current, 2=end
OUT
int 1=success, 0=fail

Moves file cursor to the specified position in file.
If mode is 0, pos position is considered from the beginning of the file and it must be positive or zero.
If mode is 1, pos position is considered as an offset from where the cursor is right now.
If mode is 2, pos position is considered from the end of the file and it must be negative or zero.


 C/C++ source code


ftell
( lib: Files, file: ../src/gs/gslib_files.cpp )
int ftell( f )

IN
ptr f file handler
OUT
int current position or -1 if error

Returns the current position of the file cursor (in bytes).

 C/C++ source code


fwrite
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fwrite( f, buffer, size )

IN
ptr f file handler
ptr buffer memory buffer
int size number of bytes to write
OUT
int written size

Writes size bytes from given buffer, into the file at the current position of the file cursor.
If less than size is returned, then an error occured.
Take great care not to exceed of buffer's bounds.
The file must be opened for write.


 C/C++ source code


fwriteb
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fwriteb( f, v )

IN
ptr f file handler
int v number to write
OUT
int 1=success, 0=fail

Writes the byte value of the parameter v in the file f at the current position of the file cursor.
The file cursor will be incremented with 1 byte.
The file must be opened for write.


 C/C++ source code


fwritei
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fwritei( f, v )

IN
ptr f file handler
int v number to write
OUT
int 1=success, 0=fail

Writes the integer value of the parameter v in the file f at the current position of the file cursor.
Since integers in GS9 have 32bits, the file cursor will be incremented with 4 bytes.
The file must be opened for write.


 C/C++ source code


fwritef
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fwritef( f, v )

IN
ptr f file handler
flt v number to write
OUT
int 1=success, 0=fail

Writes the float value of the parameter v in the file f at the current position of the file cursor.
Floats in GS9 are stored on 32bits, so the file currsor will be incremented with 4 bytes.
The file must be opened for write.


 C/C++ source code


fwrites
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fwrites( f, s, size )

IN
ptr f file handler
str s string to write
int size size to write (optional)
OUT
int 1=success, 0=fail

Writes size characters from string s in file f at the current position of the file cursor.
If size is greater then the string's length, the rest of the characters written will be 0.
If size is not specified, the string's length is used.
The file must be opened for write.




 C/C++ source code


fwritetext
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fwritetext( f, s )

IN
ptr f file handler
str s text line to write
OUT
int 1=success, 0=fail

Writes a line of text. EOL characters (/r/n) are written after the text.
The file must be opened for write.


 C/C++ source code


fread
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fread( f, buffer, size )

IN
ptr f file handler
ptr buffer memory buffer
int size number of bytes to read
OUT
int read size

Reads size bytes in given $buffer.
If less than size is returned, then an error occured.
Take great care not to exceed of buffer's bounds.


 C/C++ source code


freadb
( lib: Files, file: ../src/gs/gslib_files.cpp )
int freadb( f )

IN
ptr f file handler
OUT
int read byte

 C/C++ source code


freadi
( lib: Files, file: ../src/gs/gslib_files.cpp )
int freadi( f )

IN
ptr f file handler
OUT
int read integer

 C/C++ source code


freadf
( lib: Files, file: ../src/gs/gslib_files.cpp )
flt freadf( f )

IN
ptr f file handler
OUT
flt read float

 C/C++ source code


freads
( lib: Files, file: ../src/gs/gslib_files.cpp )
str freads( f, size )

IN
ptr f file handler
int size size to read (in bytes)
OUT
str read string

 C/C++ source code


freadtext
( lib: Files, file: ../src/gs/gslib_files.cpp )
str freadtext( f )

IN
ptr f file handler
OUT
str read text line

 C/C++ source code


fclose
( lib: Files, file: ../src/gs/gslib_files.cpp )
int fclose( f )

IN
ptr f file handler
OUT
int 1=success, 0=fail

Closes the file handler f.
After closing the file, the handler f becomes invalid, and the file requires another opening if more read or write is needed.


 C/C++ source code