GS9 Programming Language

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.

// will load and print the program file
func main()
{
	f = fopen("program.txt",0);        // open for read the program file
	if(f)                                 // if opened successfuly
	{
		fseek(f,0,2);                  // move read cursor to the end of the file to get the file size
		size = fsize(f);               // get file's size
		s = freads( f, buffer, size ); // read file's content as a string
		fclose(f);                     // close file
		println(s);                       // displaying the content with prinln is limited to a decent size
	}
}

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.

func main()
{
	f = fopen("testfile.txt",1);
	fwrites(f,"This is a line of text.\n");
	fwrites(f,"This is another line of text.\r\nAnd yet, another one.");
	fclose(f);
}

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