ref: 5edeca01b0622463a65c126ebcc29314013fd928
dir: /man/2/sys-bind/
.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 9P 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.