.th K_open II 4/21/86
.sh NAME
K_open \- open a file, terminal, extent, device, or subtype
.sh "MODULA SYNOPSIS"
.nf
CONST fSeid: seid;
CONST om: OpenModes;
CONST stCap: openDescriptor;
VAR od: openDescriptor;
VAR status: K_err_num;
...
status := NK_open(fSeid, om, stCap, od);
.sp
.sh "C SYNOPSIS"
seid fSeid;
KopenModes om;
openDescriptor stCap;
openDescriptor od;
int status;
...
status = K_open(fSeid, om, stCap, &od);
.sp
.fi
.sh DESCRIPTION
K_open opens the file, terminal, extent, or device specified by fSeid.
The open descriptor is returned in the arguement od.
.s3
No initialization of the device occurs when a device is opened.
Devices which are not ready (no tape mounted, etc.) can be opened, but
devices which are not physically present cannot be opened.
.s3
om
contains the requested open modes, which are
.s3
.lp 38 30
.bn om.read
Open for reading
.lp 38 30
.bn om.write
Open for writing
.lp 38 30
.bn om.exclusive_read
Open for exclusive reading
.lp 38 30
.bn om.exclusive_write
Open for exclusive writing
.i0
.bp
.s3
Only the following combinations of modes are permitted:
.s3
.nf
                     exclusive
   read    write   read    write
   true    false   false   false   Normal read.
   false   true    false   false   Normal write.
   true    true    false   false   Normal read and write.
   true    true    false   true    Exclusive write.
   true    true    true    true    Exclusive read and write.

.fi
.s3
When an open request fails because of an exclusive use blockage, an
exception is returned.  There is no blocking or delay associated with
exclusive use failure.  Note, though, that exclusive use is available
only to those with the ability to open for writing.  A lock out of all
other readers would constitute a channel.
.sh "SUBTYPES"
Subtypes are predefined openable objects which control access to other
objects.  If an object is subtyped, a requestor can open it for writing
only if the subtype is already open for writing to that process and the
open descriptor of the subtype is submitted in the stCap argument.  A
similar rule applies for reading.  Files may be created in a subtype by
providing the subtype, to be opened for reading and writing, to
K_create(II).  Subtypes are primarily used by the directory manager to
protect directories and are of limited use to most users.
.sh EXCEPTIONS
.lp 22 15
XbModes	Bad open modes.
.lp 22 15
XbadModex	Bad exclusive use mode.
.lp 22 15
XbadStCap	Bad subtype capability. Subtype is not open or
process does not have access.
.lp 22 15
XnoClass	Seid does not specify a file, terminal, extent, device
or subtype. Invalid seid.
.lp 22 15
XnoObj	Invalid seid. Object does not exist.
.lp 22 15
XodSpace	Process resource exhaustion. Too many open files.
.i0
.sh "SEE ALSO"
K_create(II), K_close(II),
seid(IIa)
