open

Definition: integer fn = open(string st1, string st2)
Description: Open a file or device, and obtain a file number. -1 is returned if the open fails. st1 is the path name of the file or device. st2 is the mode in which the file is to be opened. Possible modes are:

"r" - open text file for reading
"w" - create text file for writing
"u" - open text file for update (reading and writing)
"a" - open text file for appending
"rb" - open binary file for reading
"wb" - create binary file for writing
"ub" - open binary file for update
"ab" - open binary file for appending

Files opened for read or update must already exist. Files opened for write or append will be created if necessary. A file opened for write will be set to 0 bytes. Output to a file opened for append will start at the end of file.

Output to text files will have carriage-return characters automatically added before linefeed characters. On input, these carriage-return characters are removed. A control-Z character (ASCII 26) will signal an immediate end of file.

I/O to binary files is not modified in any way. Any byte values from 0 to 255 can be read or written.

Some typical devices that you can open are: (DEV: none of these have been tested on Phix)

"CON" - the console (screen)
"AUX" - the serial auxiliary port
"COM1" - serial port 1
"COM2" - serial port 2
"PRN" - the printer on the parallel port
"NUL" - a non-existent device that accepts and discards output

Example:
integer file_in, file_out
sequence first_line
constant ERROR = 2
file_in = open("myfile", "r")
if file_in=-1 then
    puts(ERROR, "couldn't open myfile\n")
else
    first_line = gets(file_in)
end if
file_out = open("PRN", "w") -- open printer for output
if file_out!=-1 then
    puts(1, "it worked!\n")
end if
close(file_in)
close(file_out)
See Also: getc, gets, puts, seek, where, lock_file, unlock_file, flush, close