1 files changed, 148 insertions, 0 deletions
diff --git a/man/man3/open.3 b/man/man3/open.3
new file mode 100644
index 00000000..4bc887b6
--- /dev/null
+++ b/man/man3/open.3
@@ -0,0 +1,148 @@
+.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
+.IR exec (2)
+or
+.I execl
+system call is made;
+and
+.B ORCLOSE
+says to remove the file when it is closed (by everyone who has a copy of the file descriptor).
+.I Open
+fails if the file does not exist or the user does not have
+permission to open it for the requested purpose
+(see
+.IR stat (2)
+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
+.IR exec (2)),
+.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 (5).
+.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 (2))
+then the constituent directory where the file is created
+depends on the structure of the union: see
+.IR bind (2).
+.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 (5)
+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 /sys/src/libc/9syscall
+.SH SEE ALSO
+.IR intro (2),
+.IR bind (2),
+.IR stat (2)
+.SH DIAGNOSTICS
+These functions set
+.IR errstr .