# 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