MongooseAll help topics · Link to this topic
Showing help on 'file_open()'
Function: FHANDLE file_open(STR pathname, STR mode)Raises: E_INVARG if mode is not a valid mode, E_QUOTA if too many files are open.
This opens a file specified by pathname and returns an FHANDLE for it.
It ensures pathname is legal. Mode is a string of characters indicating what mode the file is opened in.
The mode string is four characters.
The first character must be (r)ead, (w)rite, or (a)ppend. The second must be '+' or '-'. This modifies the previous argument.
o r- opens the file for reading and fails if the file does not exist.
o r+ opens the file for reading and writing and fails if the file
does not exist.
o w- opens the file for writing, truncating if it exists and creating
if not.
o w+ opens the file for reading and writing, truncating if it exists
and creating if not.
o a- opens a file for writing, creates it if it does not exist and
positions the stream at the end of the file.
o a+ opens the file for reading and writing, creates it if does not
exist and positions the stream at the end of the file.
The third character is either (t)ext or (b)inary. In text mode,
data is written as-is from the MOO and data read in by the MOO is
stripped of unprintable characters. In binary mode, data is
written filtered through the binary-string->raw-bytes conversion
and data is read filtered through the raw-bytes->binary-string
conversion. For example, in text mode writing " 1B" means three
bytes are written: ' ' Similarly, in text mode reading " 1B" means
the characters ' ' '1' 'B' were present in the file. In binary
mode reading " 1B" means an ASCII ESC was in the file. In text
mode, reading an ESC from a file results in the ESC getting
stripped.
It is not recommended that files containing unprintable ASCII data be
read in text mode, for obvious reasons.
The final character is either 'n' or 'f'. If this character is 'f',
whenever data is written to the file, the MOO will force it to finish
writing to the physical disk before returning. If it is 'n' then
this won't happen.
This is implemented using fopen().