20060303-partial

1 files changed, 201 insertions, 0 deletions

diff --git a/man/2/sys-bind b/man/2/sys-bind
new file mode 100644
index 00000000..b03379c0
--- /dev/null
+++ b/man/2/sys-bind
@@ -0,0 +1,201 @@
+.TH SYS-BIND 2
+.SH NAME
+bind, mount, unmount \- change file name space
+.SH SYNOPSIS
+.EX
+include "sys.m";
+sys := load Sys Sys->PATH;
+
+bind:     fn(name, old: string, flag: int): int;
+mount:    fn(fd: ref FD; afd: ref FD, old: string, flag: int, aname: string):
+             int;
+unmount:  fn(name, old: string): int;
+.EE
+.SH DESCRIPTION
+.B Bind
+and
+.B mount
+modify the file name space of the current process and its name space group.
+For both calls,
+.I old
+is the name of an existing file or directory in the
+current name space where the modification is to be made.
+The name
+.I old
+is
+evaluated
+as described in
+.IR sys-intro (2)
+except that no translation of the final path element is done.
+.PP
+For
+.BR bind ,
+.I name
+is the name of another (or possibly the same)
+existing file or directory in
+the current name space.
+After a successful
+.B bind
+call, the file name
+.I old
+is an alias for the object originally named by
+.IR name ;
+if the modification does not hide the original,
+.I name
+will also still refer to its original file.
+The evaluation of
+.I name
+happens at the time of the
+.BR bind ,
+not when the binding is later used.
+.PP
+The
+.I fd
+argument to
+.B mount
+is a file descriptor of an open pipe or network connection
+to a file server ready to receive Styx messages.
+The
+.I old
+file must be a directory.
+After a successful
+.BR mount ,
+the file tree
+.I served
+(see below) by
+.I fd
+will be visible with its root directory having name
+.IR old .
+If the requested service requires authentication, the file descriptor
+.I afd
+must be open on an authentication file for the
+requested service;
+otherwise it should be
+.BR nil .
+.PP
+The
+.I flag
+controls details of the modification made to the name space.
+In the following,
+.I new
+refers to the file
+as defined by
+.I name
+or the root directory served by
+.IR fd .
+Either both
+.I old
+and new files must be directories,
+or both must not be directories.
+.I Flag
+can be one of:
+.TF Sys->MBEFORE
+.TP 
+.B Sys->MREPL
+Replace the
+.I old
+file by the new one.
+Henceforth, an evaluation of
+.I old
+will be translated to the new file.
+If they are directories (for
+.BR mount ,
+this condition is true by definition),
+.I old
+becomes a
+.I "union directory"
+consisting of one directory (the new file).
+.TP
+.B Sys->MBEFORE
+Both the
+.I old
+and new files must be directories.
+Add the constituent files of the new directory
+to the union directory at
+.I old
+so its contents appear first in the union.
+After a
+.B Sys->MBEFORE
+.B bind
+or
+.BR mount ,
+the new directory will be searched first when evaluating file names
+in the union directory.
+.TP
+.B Sys->MAFTER
+Like
+.B Sys->MBEFORE
+but the new directory goes at the end of the union.
+.PD
+.PP
+In addition, there is a
+.B Sys->MCREATE
+flag that can be OR'd with any of the above.
+When a
+.B create
+call (see
+.IR sys-open (2))
+attempts to create in a union directory, and the file does not exist,
+the elements of the union are searched in order until one is found
+with
+.B Sys->MCREATE
+set.
+The file is created in that directory; if that attempt fails,
+the
+.B create
+fails.
+.PP
+With
+.BR mount ,
+the file descriptor
+.I fd
+must be open for reading and writing
+and connected to a file server.
+After the
+.BR mount ,
+the file tree starting at
+.I old
+is served by a kernel
+.IR mnt (3)
+device.
+That device will turn operations in the tree into messages to the server on
+.IR fd .
+.I Aname
+selects among different
+file trees on the server; the
+empty (or nil)
+string chooses the default tree.
+.PP
+The effects of
+.B bind
+and
+.B mount
+can be undone by
+.BR unmount .
+If
+.I name
+is
+.BR nil ,
+everything bound to or mounted upon
+.I old
+is unbound or unmounted.
+If
+.I name
+is not
+.BR nil ,
+it is evaluated as described above for
+.BR bind ,
+and the effect of binding or mounting that particular result on
+.I old
+is undone.
+.SH SEE ALSO
+.IR sys-intro (2)
+.SH DIAGNOSTICS
+The return value is a positive integer (a unique sequence number) for
+success, \-1 for failure.
+.SH BUGS
+.B Mount
+will not return until it has successfully attached
+to the file server, so the thread doing a
+.B mount
+cannot be the one serving.