_OPEN - open file with options.
(GCOS8 only)
Usage:
#include <host_io.h>
u = _open(action1, arg1, action2, arg2, ...);
Examples:
u = _open(OA_FNAME, "/myfile", OA_READ);
Where:
- OPNACT action1, action2, ...;
- indicate various actions that "_open" should take.
See below for a list of the action names and their meanings.
- arg1, arg2, ...
- are arguments associated with actions (if necessary).
Each action may be followed by zero or more of these arguments
to specify particular details about the operation.
The type of the argument depends on the action; see below.
- FILE *u;
- is a "file pointer".
This points to a structure that contains information needed for
subsequent I/O on the file being opened.
Description:
"_open" serves the same purpose as the ANSI standard "fopen"
function, but is unique to GCOS8.
It lets you open files with more flexibility than "fopen".
Because of its flexible format, more features may be added
to "_open" as the library evolves.
Actions
The following is a list of the actions which are currently
supported.
Some actions may be followed by one or more argument values.
- OA_FNAME, char *fname
- specifies the name of a file to be opened.
- OA_STR, char *buf
- opens a stream for core-to-core I/O.
"buf" points to the first character to be read or written.
Every call to "_open" should have either OA_FNAME or OA_STR
as one of its actions.
- OA_READ
- opens the file for reading.
- OA_WRITE
- opens the file for writing.
If both OA_READ and OA_WRITE are specified, the file will
initially be opened for reading or writing, whichever is
specified last in the option list.
However, the file will be accessed with both read and write permissions
so that you can switch from reading to writing or vice versa
later on.
- OA_APPEND
- opens the file for append.
- OA_RAW
- uses the stream for block mode access only.
If you open a stream in this way, you should not use
any character stream or record type calls on the stream.
- OA_RANDOM
- accesses the file as a random file.
- OA_RETFIL
- indicates that the file should always be deaccessed
when it is closed.
Normally, the initial state of the file determines whether
it should be deaccessed when it is closed.
- OA_PERM_BLK
OA_TEMP_BLK
- are for internal use of the library and should
not be used with "_open".
- OA_MEDIA_REPORT, int mr
- specifies the media and report code to use when writing the file.
'mr' is an integer value of the form "00000000mmrr" where "mm" are
two octal digits in the range 0-017 specifying the media code,
and "rr" are two octal digits giving the report code.
- OA_ERET
- tells the I/O library to return an error status
if I/O errors occur when reading or writing the file.
If this option is not specified, the program simply issues
an appropriate error message and terminates with "exit(EXIT_FAILURE)"
if I/O errors occur.
The OA_ERET option is very seldom needed.
- OA_CREATE, int fsize
- uses an initial allocation size of
"fsize" llinks when creating the file,
provided that the file is being opened for writing
and does not already exist.
If "fsize" is zero, the file will not be created.
- OA_BUFSIZ, int words
- specifies the size of the buffer to use for I/O on the file,
measured in machine words.
This must be a multiple of 320 words.
The default is 56 llinks (56*320 words).
- OA_ITYPE
- tells "_open" not to generate an error if a random
file is opened as a sequential file, or vice versa.
- OA_W_END
- forces all writes to append to end of the file.
- OA_ERRNO, int *stat
- controls what happens if "_open" encounters an error.
By default, if a call to "_open" fails, the program is terminated
with an appropriate error message, and "_open" never returns.
However, if OA_ERRNO is specified and the open fails, "_open"
returns NULL and places an "errno" type status value in "*stat".
- OA_BINARY
- opens the file for C style binary byte I/O.
- OA_NSHARE
- opens the file for non-concurrent access.
Normally, the "_open" will request access allowing concurrent
read/write accesses to the file.
- OA_EXEC
- is used after OA_READ, to specify that the file is to be
accessed requesting execute access.
- OA_LOAD
- is used after OA_WRITE to specify that the file is to accessed
with LOAD access.
- OA_NOREWIND
- does not rewind a sequential file to position zero
during the open operation.
Copyright © 2000, Thinkage Ltd.