sys/man/2/bind

   1 .TH BIND 2
   2 .SH NAME
   3 bind, mount, unmount \- change name space
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .B
  10 int bind(char *name, char *old, int flag)
  11 .PP
  12 .B
  13 int mount(int fd, int afd, char *old, int flag, char *aname)
  14 .PP
  15 .B
  16 int unmount(char *name, char *old)
  17 .SH DESCRIPTION
  18 .I Bind
  19 and
  20 .I mount
  21 modify the file name space of the current process and other
  22 processes in its name space group
  23 (see
  24 .IR fork (2)).
  25 For both calls,
  26 .I old
  27 is the name of an existing file or directory in the
  28 current name space where the modification is to be made.
  29 The name
  30 .I old
  31 is
  32 .I evaluated
  33 as described in
  34 .IR intro (2),
  35 except that no translation of the final path element is done.
  36 .PP
  37 For
  38 .IR bind ,
  39 .I name
  40 is the name of another (or possibly the same)
  41 existing file or directory in
  42 the current name space.
  43 After a successful
  44 .I bind
  45 call, the file name
  46 .I old
  47 is an alias for the object originally named by
  48 .IR name ;
  49 if the modification doesn't hide it,
  50 .I name
  51 will also still refer to its original file.
  52 The evaluation of
  53 .I new
  54 happens at the time of the
  55 .IR bind ,
  56 not when the binding is later used.
  57 .PP
  58 The
  59 .I fd
  60 argument to
  61 .I mount
  62 is a file descriptor of an open network connection
  63 or pipe to a file server, while
  64 .I afd
  65 is a authentication file descriptor as created by
  66 .IR fauth (2)
  67 and subsequently authenticated.
  68 If authentication is not required,
  69 .I afd
  70 should be -1.
  71 The
  72 .I old
  73 file must be a directory.
  74 After a successful
  75 .I mount
  76 the file tree
  77 .I served
  78 (see below) by
  79 .I fd
  80 will be visible with its root directory having name
  81 .IR old .
  82 .PP
  83 The
  84 .I flag
  85 controls details of the modification made to the name space.
  86 In the following,
  87 .I new
  88 refers to the file
  89 as defined by
  90 .I name
  91 or the root directory served by
  92 .IR fd .
  93 Either both
  94 .I old
  95 and new files must be directories,
  96 or both must not be directories.
  97 .I Flag
  98 can be one of:
  99 .TF MBEFORE
 100 .TP
 101 .B MREPL
 102 Replace the
 103 .I old
 104 file by the new one.
 105 Henceforth, an evaluation of
 106 .I old
 107 will be translated to the new file.
 108 If they are directories (for
 109 .IR mount ,
 110 this condition is true by definition),
 111 .I old
 112 becomes a
 113 .I "union directory"
 114 consisting of one directory (the new file).
 115 .TP
 116 .B MBEFORE
 117 Both the
 118 .I old
 119 and new files must be directories.
 120 Add the constituent files of the new directory
 121 to the union directory at
 122 .I old
 123 so its contents appear first in the union.
 124 After an
 125 .B MBEFORE
 126 .I bind
 127 or
 128 .IR mount ,
 129 the new directory will be searched first when evaluating file names
 130 in the union directory.
 131 .TP
 132 .B MAFTER
 133 Like
 134 .B MBEFORE
 135 but the new directory goes at the end of the union.
 136 .PD
 137 .PP
 138 The flags are defined in
 139 .BR <libc.h> .
 140 In addition, there is an
 141 .B MCREATE
 142 flag that can be OR'd with any of the above.
 143 When a
 144 .I create
 145 system call (see
 146 .IR open (2))
 147 attempts to create in a union directory, and the file does not exist,
 148 the elements of the union are searched in order until one is found
 149 with
 150 .B MCREATE
 151 set.
 152 The file is created in that directory; if that attempt fails,
 153 the
 154 .I create
 155 fails.
 156 .PP
 157 Finally, the
 158 .B MCACHE
 159 flag, valid for
 160 .I mount
 161 only, turns on caching for files made available by the mount.
 162 By default, file contents are always retrieved from the server.
 163 With caching enabled, the kernel may instead use a local cache to satisfy
 164 .IR read (5)
 165 requests for files accessible through this mount point.
 166 The currency of cached data for a file is verified at each
 167 .IR open (5)
 168 of the file from this client machine.
 169 .PP
 170 With
 171 .IR mount ,
 172 the file descriptor
 173 .I fd
 174 must be open for reading and writing
 175 and prepared to respond to 9P messages
 176 (see Section 5).
 177 After the
 178 .IR mount ,
 179 the file tree starting at
 180 .I old
 181 is served by a kernel
 182 .IR mnt (3)
 183 device.
 184 That device will turn operations in the tree into messages on
 185 .IR fd .
 186 .I Aname
 187 selects among different
 188 file trees on the server; the null string chooses the default tree.
 189 .PP
 190 The file descriptor
 191 .I fd
 192 is automatically closed by a successful
 193 .I mount
 194 call.
 195 .PP
 196 The effects of
 197 .I bind
 198 and
 199 .I mount
 200 can be undone by
 201 .IR unmount .
 202 If
 203 .I name
 204 is zero, everything bound to or mounted upon
 205 .I old
 206 is unbound or unmounted.
 207 If
 208 .I name
 209 is not zero, it is evaluated as described above for
 210 .IR bind ,
 211 and the effect of binding or mounting that particular result on
 212 .I old
 213 is undone.
 214 .SH SOURCE
 215 .B /sys/src/libc/9syscall
 216 .SH SEE ALSO
 217 .IR bind (1),
 218 .IR intro (2),
 219 .IR fcall (2),
 220 .IR auth (2)
 221 (particularly
 222 .BR amount ),
 223 .IR intro (5),
 224 .IR mnt (3),
 225 .IR srv (3)
 226 .SH DIAGNOSTICS
 227 The return value is a positive integer (a unique sequence number) for
 228 success, -1 for failure.
 229 These routines set
 230 .IR errstr .
 231 .SH BUGS
 232 .I Mount
 233 will not return until it has successfully attached
 234 to the file server, so the process doing a
 235 .I mount
 236 cannot be the one serving.