10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
173 lines
3.9 KiB
Groff
173 lines
3.9 KiB
Groff
.TH OPEN 3
|
|
.SH NAME
|
|
open, create, close \- open a file for reading or writing, create file
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
int open(char *file, int omode)
|
|
.PP
|
|
.B
|
|
int create(char *file, int omode, ulong perm)
|
|
.PP
|
|
.B
|
|
int close(int fd)
|
|
.SH DESCRIPTION
|
|
.I Open
|
|
opens the
|
|
.I file
|
|
for I/O and returns an associated file descriptor.
|
|
.I Omode
|
|
is one of
|
|
.BR OREAD ,
|
|
.BR OWRITE ,
|
|
.BR ORDWR ,
|
|
or
|
|
.BR OEXEC ,
|
|
asking for permission to read, write, read and write, or execute, respectively.
|
|
In addition, there are three values that can be ORed with the
|
|
.IR omode :
|
|
.B OTRUNC
|
|
says to truncate the file
|
|
to zero length before opening it;
|
|
.B OCEXEC
|
|
says to close the file when an
|
|
.MR exec 3
|
|
or
|
|
.I execl
|
|
system call is made;
|
|
.B ORCLOSE
|
|
says to remove the file when it is closed (by everyone who has a copy of the file descriptor);
|
|
and
|
|
.B OAPPEND
|
|
says to open the file in append-only mode, so that writes
|
|
are always appended to the end of the file.
|
|
.I Open
|
|
fails if the file does not exist or the user does not have
|
|
permission to open it for the requested purpose
|
|
(see
|
|
.MR stat 3
|
|
for a description of permissions).
|
|
The user must have write permission on the
|
|
.I file
|
|
if the
|
|
.B OTRUNC
|
|
bit is set.
|
|
For the
|
|
.I open
|
|
system call
|
|
(unlike the implicit
|
|
.I open
|
|
in
|
|
.MR exec 3 ),
|
|
.B OEXEC
|
|
is actually identical to
|
|
.BR OREAD .
|
|
.PP
|
|
.I Create
|
|
creates a new
|
|
.I file
|
|
or prepares to rewrite an existing
|
|
.IR file ,
|
|
opens it according to
|
|
.I omode
|
|
(as described for
|
|
.IR open ),
|
|
and returns an associated file descriptor.
|
|
If the file is new,
|
|
the owner is set to the userid of the creating process group;
|
|
the group to that of the containing directory;
|
|
the permissions to
|
|
.I perm
|
|
ANDed with the permissions of the containing directory.
|
|
If the file already exists,
|
|
it is truncated to 0 length,
|
|
and the permissions, owner, and group remain unchanged.
|
|
The created file is a directory if the
|
|
.B DMDIR
|
|
bit is set in
|
|
.IR perm ,
|
|
an exclusive-use file if the
|
|
.B DMEXCL
|
|
bit is set, and an append-only file if the
|
|
.B DMAPPEND
|
|
bit is set.
|
|
Exclusive-use files may be open for I/O by only one client at a time,
|
|
but the file descriptor may become invalid if no I/O is done
|
|
for an extended period; see
|
|
.IR open (9p).
|
|
.PP
|
|
.I Create
|
|
fails if the path up to the last element of
|
|
.I file
|
|
cannot be evaluated, if the user doesn't have write permission
|
|
in the final directory, if the file already exists and
|
|
does not permit the access defined by
|
|
.IR omode ,
|
|
of if there there are no free file descriptors.
|
|
In the last case, the file may be created even when
|
|
an error is returned.
|
|
.\" If the file is new and the directory in which it is created is
|
|
.\" a union directory (see
|
|
.\" .IR intro (3))
|
|
.\" then the constituent directory where the file is created
|
|
.\" depends on the structure of the union: see
|
|
.\" .IR bind (3).
|
|
.PP
|
|
Since
|
|
.I create
|
|
may succeed even if the file exists, a special mechanism is necessary
|
|
for those applications that require an atomic create operation.
|
|
If the
|
|
.B OEXCL
|
|
.RB ( 0x1000 )
|
|
bit is set in the
|
|
.I mode
|
|
for a
|
|
.IR create,
|
|
the call succeeds only if the file does not already exist;
|
|
see
|
|
.IR open (9p)
|
|
for details.
|
|
.PP
|
|
.I Close
|
|
closes the file associated with a file descriptor.
|
|
Provided the file descriptor is a valid open descriptor,
|
|
.I close
|
|
is guaranteed to close it; there will be no error.
|
|
Files are closed automatically upon termination of a process;
|
|
.I close
|
|
allows the file descriptor to be reused.
|
|
.SH SOURCE
|
|
.B \*9/src/lib9
|
|
.SH SEE ALSO
|
|
.MR intro 3 ,
|
|
.MR stat 3
|
|
.SH DIAGNOSTICS
|
|
These functions set
|
|
.IR errstr .
|
|
.SH BUGS
|
|
Not all functionality is supported on all systems.
|
|
.PP
|
|
The
|
|
.B DMAPPEND
|
|
bit is not supported on any systems.
|
|
.PP
|
|
The implementation of
|
|
.B ORCLOSE
|
|
is to unlink the file after opening it, causing problems
|
|
in programs that try to access the file by name before it is closed.
|
|
.PP
|
|
To avoid name conflicts with the underlying system,
|
|
.I open
|
|
and
|
|
.I create
|
|
are preprocessor macros defined as
|
|
.IR p9open
|
|
and
|
|
.IR p9create ;
|
|
see
|
|
.MR intro 3 .
|