path: root/man/1/bind

.TH BIND 1
.SH NAME
bind, mount, unmount \- change name space
.SH SYNOPSIS
.B bind
[
.I option ...
]
.I source target
.PP
.B mount
[
.I option ...
]
.I source target
[
.I spec
]
.PP
.B unmount
[
.I source
]
.I target
.SH DESCRIPTION
The
.IR bind
and
.IR mount
commands modify the file name space of the current process
and other processes in the same name space group
(see
.IR sys-pctl (2)).
For both calls, 
.I target
is the name of an existing file or directory in the
current name space where the modification is to be made.
.PP
For
.IR bind ,
.I source
is the name of an existing file or directory in the current name space.
After a successful
.IR bind ,
the file name
.I target
is an alias for the object originally named by
.IR source ;
if the modification doesn't hide it,
.I source
will also still refer to its original file.
The evaluation of
.I source
(see
.IR sys-intro (2))
happens at the time of the
.IR bind ,
not when the binding is later used.
.PP
Both
.I source
and
.I target
files must be of the same type: either both directories or both files.
.PP
For 
.IR mount,
.I source
can be a 
shell command,
a network address,
or a file name.
If
.I source
is surrounded by brace characters
.RB ( {
and
.BR } ),
it is invoked as a
.IR sh (1)
command and its standard input is mounted (no
authentication takes place in this case).
If
.I source
contains an exclamation mark
.RB ( ! ),
or there is no file of that name,
it is assumed to be a network address for a machine acting
as a file server.
This argument should then conform to the conventions
described in
.IR sys-dial (2).
Otherwise
.I source
should be the name of a file that when opened gives a connection
to a file server, something serving the Styx protocol
described in
.IR intro (5).
The optional
.I spec
argument to
.I mount
is passed in the
.IR attach (5)
message and selects amongst different file trees offered by the server.
.PP
The effects of
.I bind
and
.I mount
can be undone by
.IR unmount .
If two arguments are given to 
.IR unmount ,
the effect is to undo a
.I bind
or
.I mount
with the same arguments. If only one argument is given, everything bound to or mounted on
.I target
is unmounted.
.PP
By default,
.I bind
and
.IR mount
replace the
.I target
file by the new one,
.IR source .
Henceforth, an evaluation of the pathname
.I target
will be translated to the new file.
If they are directories (for
.IR mount ,
this condition is true by definition),
.I target
becomes a
.I "union directory"
consisting of one directory (the 
.IR source
directory).
.PP
A union directory unites the contents of the source and target directories.
If the same name appears in both directories, the name used is the one in the
directory that is bound before the other.
In particular, if the directories have subdirectories of the same name, only
the contents of the subdirectory in the top directory will be seen.
If the subdirectory contents are themselves to be united, that must be done
first in a separate
.I bind
or
.IR mount .
.PP
Note that the
.B #
character in the name of a kernel device
must be quoted when used in a
.I bind
or
.I unmount
command, or the shell will take it as the start of a comment.
.PP
Options control aspects of the modification to the name space:
.TP
.B -b
Both files must be directories.
Add the 
.IR source
directory to the beginning
of the union directory represented by the 
.IR target 
directory.
.TP
.B -a
Both files must be directories.
Add the 
.IR
source 
directory to the end
of the union directory represented by the 
.IR target 
directory.
.TP
.B -c
This can be used in addition to any of the above to permit
creation in a union directory.
When a new file is created in a union directory,
it is placed in the first element of the union that has been
bound or mounted with the
.B -c
option.
If that directory has not got write permission,
the create fails.
.TP
.B -q
Exit quietly without printing a diagnostic if the bind or mount fails.
.TP
.B -A
For 
.I mount
only. Do not authenticate the connection to the server before proceeding with
.IR mount .
Otherwise the connection is authenticated by
.IR security-auth (2).
.TP
.BI -C " alg"
For
.I mount
only,
specify the algorithm, 
.IR alg ,
to be used following authentication for digesting or encryption. See 
.IR ssl (3)
for the supported algorithms.
The default is
.BR none :
.IR ssl (3)
is not used after authentication.
.TP
.BI -k " kfile "
For mount only, specify the keyfile to be used when authenticating.
The default is
.BI /usr/ user /keyring/default .
See 
.IR keyring-auth (2)
for more details.
.TP
.B -9
For
.I mount
only, and only when hosted on Plan 9.
.I Source
is a Plan 9 file server; use Plan 9's
.I factotum
as authentication agent to authenticate the mount.
(Note that a Plan 9 file service that is known not to authenticate can be mounted from
any Inferno host, by using the
.B -A
option to suppress Inferno authentication.)
The existing Plan 9 file servers do not encrypt connections, so the
.B -C
and
.B -k
options are ignored.
.TP
.B -P
When
.I source
is a network address, use
.IR styxpersist (2)
to try to simulate a permanent connection, even should the server reboot.
Note the caveats on that page.
.TP
.B -o
For
.I mount
only,
the file server serves the original version of the Styx protocol, and
.I mount
inserts a process that translates to the current version.
.SH SOURCE
.B /appl/cmd/bind.b
.br
.B /appl/cmd/mount.b
.br
.B /appl/cmd/unmount.b
.SH SEE ALSO
.IR sh (1),
.IR keyring-auth (2),
.IR security-auth (2),
.IR sys-intro (2),
.IR sys-bind (2),
.IR sys-dial (2),
.IR intro (3),
.IR getauthinfo (8)