SYS-OPEN(2)SYS-OPEN(2)NAME
open, create - open a file for reading or writing, create file
SYNOPSIS
include "sys.m";
sys := load Sys Sys->PATH;
create: fn(file: string, omode, perm: int): ref FD;
open: fn(file: string, omode: int): ref FD;
DESCRIPTION
Open opens the file for I/O and returns an associated file descriptor.
Omode is one of Sys->OREAD, Sys->OWRITE, or Sys->ORDWR, asking for per‐
mission to read, write, or read and write, respectively. There are two
values that can be OR'd with those to form omode: Sys->OTRUNC says to
truncate the file before opening it, which requires write permission
even if omode is Sys->OREAD; and Sys->ORCLOSE says to remove the file
when it is closed (ie, when the last reference to this file descriptor
goes away).
Open returns nil if the file does not exist, if the file name is unac‐
ceptable, if the user does not have permission to open it as requested
(see sys-stat(2) for a description of permissions), or if any other
error occurs.
Create creates a new file or prepares to rewrite an existing file,
opens it according to omode (as described for open), and returns an
associated file descriptor.
If the file is new, the owner is set to the user id of the creating
process group, the group to that of the containing directory, and the
permissions to perm ANDed with the permissions of the containing direc‐
tory. The bits in perm are the same as those in the file mode returned
by sys-stat(2).
If the file already exists, it is truncated to 0 length, but the per‐
missions, owner, and group remain unchanged.
The created file will be a directory if the Sys->DMDIR bit is set in
perm, and omode is Sys->OREAD. The file will be exclusive-use if the
Sys->DMEXCL bit is set in perm and the underlying file server supports
it; see open(5) for details. It will be append-only if the Sys->DMAP‐
PEND bit is set, and the underlying file server supports it.
Create returns nil if the path up to the last element of file cannot be
evaluated, if the file name is unacceptable, if the user does not have
write permission in the final directory, if the file already exists and
does not permit the access defined by omode, or if any other error
occurs.
If the file is new and the directory in which it is created is a union
directory (see sys-intro(2)) then the constituent directory where the
file is created depends on the structure of the union: see sys-bind(2).
Since create may succeed even if the file exists, a special mechanism
is necessary for applications that require an atomic create operation.
If the Sys->OEXCL bit is set in the mode for a create, the call suc‐
ceeds only if the file does not already exist; see open(5) for details.
There is no explicit ``close'' routine: when the last reference to the
file descriptor is released, the system closes the associated file.
For devices and network protocols where shutdown must be guaranteed,
write a hangup message to the associated control file and use the
return value of the write to verify closure.
SEE ALSOsys-intro(2), sys-bind(2), sys-stat(2)SYS-OPEN(2)
