Expand/Shrink

open

Definition: integer fn = open(sequence filename, object openmode)
Description: Open a file or device, and obtain a file number.
filename: the path name of the file or device.
openmode: the mode in which the file is to be opened.
-1 is returned if the open fails.
pwa/p2js: Not supported.
comments: 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 are created if necessary.
A file opened for write is set to 0 bytes.
Output to a file opened for append starts at the end of file.
The length-1 modes may be specified as a single character, reducing irritation when translating code from another language such as C.

Output to text files (as opposed to binary) has carriage-return characters automatically added before linefeed characters.
On input from text files, such carriage-return characters are removed.
A control-Z character (ASCII 26) signals 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

Note that open() does not support forwardslash ('/') and backslash ('\\') seamlessly on all platforms, instead of say open(`..\unixdict.txt`,"r"), use
open(join_path({"..","unixdict.txt"}),"r") [preferred/faster/simpler] or
open(get_proper_path(`..\unixdict.txt`),"r") or even
open(iff(platform()=WINDOWS?`..\unixdict.txt`:`../unixdict.txt`),"r").
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)
Implementation: via :%opOpen / fopen() in builtins\VM\pfileioN.e (an autoinclude) - be warned however it is low-level complicated stuff that you do not need to know.
See Also: getc, gets, puts, seek, where, lock_file, unlock_file, flush, close, join_path, get_proper_path