_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(-1)" if I/O errors occur. Because of the "exit(-1)", programs will NOT get wrap-up. 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.