sys/man/3/fs

   1 .TH FS 3
   2 .SH NAME
   3 fs \- file system devices
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind -b #k /dev
   7 .sp 0.3v
   8 .B /dev/fs
   9 .B /dev/fs/ctl
  10 .B /dev/fs/...
  11 .B /dev/\fInew\fP
  12 .fi
  13 .SH DESCRIPTION
  14 The
  15 .I fs
  16 driver builds complex disk files out of simpler disk files.
  17 Inspired by the Plan 9 file server kernel's configuration strings,
  18 it provides device mirroring, partitioning, interleaving, and catenation
  19 for disk-based services like
  20 .IR venti (8).
  21 .PP
  22 The device is intended to be bound at
  23 .B /dev
  24 and initially contains a directory named
  25 .BR fs ,
  26 which in turn contains a
  27 .B ctl
  28 file and one file per configured device.
  29 .PP
  30 Most control messages introduce a new device, here named
  31 .IR new .
  32 The
  33 .I file
  34 arguments are interpreted in the name space of the writing process.
  35 .PP
  36 The device name
  37 .I new
  38 may be a single filename component (containing no slashes);
  39 in this case, the device is created under
  40 .BR #k/fs .
  41 If
  42 .I new
  43 instead has the format
  44 .IB dir / file,
  45 the device is made available at
  46 .BI #k/ dir / file.
  47 The directory
  48 .I dir
  49 goes away when the last device on it is removed with the
  50 .B del
  51 control message,
  52 but
  53 .B #k/fs
  54 will never be removed.
  55 .TF "del \fIold
  56 .PD
  57 .TP
  58 .BI cat " new files" \fR...
  59 The device
  60 .I new
  61 corresponds to the catenation of
  62 .IR files .
  63 .TP
  64 .BI inter " new files" \fR...
  65 The device
  66 .I new
  67 corresponds to the block interleaving of
  68 .IR files ;
  69 an 8192-byte block size is assumed.
  70 .TP
  71 .BI mirror " new files" \fR...
  72 The device
  73 .I new
  74 corresponds to a RAID-1-like mirroring of
  75 .IR files .
  76 Writes to
  77 .BI new
  78 are handled by sequentially writing the same data to the
  79 .I files
  80 from right to left (the reverse of
  81 the order in the control message).
  82 A failed write causes an eventual error return
  83 but does not prevent the rest of the writes
  84 to the other devices of the mirror set.
  85 Reads from
  86 .BI new
  87 are handled by sequentially reading from the
  88 .I files
  89 from left to right until one succeeds.
  90 The length of the mirror device is the minimum of the lengths of the
  91 .IR files .
  92 .TP
  93 .BI part " new file offset length"
  94 .TP
  95 .BI part " new offset end
  96 In the first form,
  97 the device
  98 .I new
  99 corresponds to the
 100 .I length
 101 units starting at
 102 .I offset
 103 in
 104 .IR file .
 105 If
 106 .IR offset + length
 107 reaches past the end of
 108 .IR file ,
 109 .I length
 110 is silently reduced to fit.
 111 Units are bytes.
 112 In the second form,
 113 a previous
 114 .B disk
 115 request must have defined the source
 116 .I file
 117 for further requests and the end of the device
 118 is determined by the
 119 .I end
 120 offset in the source file, and not by the device
 121 length. Units are as defined in the previous
 122 .B disk
 123 request. This form is accepted for compatibility with
 124 .IR fdisk
 125 (in
 126 .IR prep (8))
 127 and
 128 .IR sd (3)
 129 devices.
 130 .TP
 131 .BI del " old
 132 Removes the device named
 133 .IR old .
 134 The device will still be seen while in use.
 135 Further I/O attempts will fail with an error indication stating that
 136 the device is gone.
 137 When
 138 .I old
 139 is
 140 .IB dir /*\fR,
 141 all devices under
 142 .I dir
 143 are removed.
 144 .TP
 145 .BI disk " dir [ n file ]
 146 makes
 147 .I dir
 148 implicit in new device names (i.e., it makes
 149 .I new
 150 mean
 151 .IB dir / new
 152 by default).
 153 Optional argument
 154 .I n
 155 specifies the default unit (sector) size in bytes and the default source
 156 .I file
 157 for further partition devices.
 158 Default values are restored when the control file is closed.
 159 .TP
 160 .BI crypt " new file key"
 161 The device
 162 .I new
 163 corresponds to a AES-encrypted partition
 164 .I file
 165 encrypted with
 166 .I key (see
 167 .IR cryptsetup (8)).
 168 .TP
 169 .B clear
 170 Discard all
 171 .I fs
 172 device definitions.
 173 .PD
 174 .LP
 175 If the variable
 176 .B fsconfig
 177 is set in
 178 .IR plan9.ini (8),
 179 .I fs
 180 will read its configuration from the file
 181 .B $fsconfig
 182 on the first attach.
 183 This is useful when the machine boots from a local file server that uses
 184 .IR fs .
 185 .SH EXAMPLES
 186 Use a previously partitioned disk,
 187 .BR /dev/sdC0 ,
 188 making
 189 partition files available under
 190 .BR /dev/sdC0parts :
 191 .IP
 192 .EX
 193 {
 194         echo disk sdC0parts 512 /dev/sdC0/data
 195         disk/fdisk -p /dev/sdC0/data
 196         # now create plan 9 partitions
 197         echo disk sdC0parts 512 /dev/sdC0parts/plan9
 198         disk/prep -p /dev/sdC0parts/plan9
 199 } > /dev/fs/ctl
 200 .EE
 201 .LP
 202 Mirror the two disks
 203 .B /dev/sdC0/data
 204 and
 205 .B /dev/sdD0/data
 206 as
 207 .BR /dev/fs/m0 ;
 208 similarly, mirror
 209 .B /dev/sdC1/data
 210 and
 211 .B /dev/sdD1/data
 212 as
 213 .BR /dev/fs/m1 :
 214 .IP
 215 .EX
 216 echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/fs/ctl
 217 echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/fs/ctl
 218 .EE
 219 .LP
 220 Interleave the two mirrored disks to create
 221 .BR /dev/fs/data :
 222 .IP
 223 .EX
 224 echo inter data /dev/fs/m0 /dev/fs/m1 >/dev/fs/ctl
 225 .EE
 226 .LP
 227 Run
 228 .IR kfs (4)
 229 on the interleaved device:
 230 .IP
 231 .EX
 232 disk/kfs -f /dev/fs/data
 233 .EE
 234 .LP
 235 Save the configuration:
 236 .IP
 237 .EX
 238 cp /dev/fs/ctl /dev/fd0disk
 239 .EE
 240 .LP
 241 To load the configuration automatically at boot time,
 242 add this to
 243 .IR plan9.ini :
 244 .IP
 245 .EX
 246 fsconfig=/dev/fd0disk
 247 .EE
 248 .SH "SEE ALSO"
 249 .I read
 250 in
 251 .IR cat (1),
 252 .IR dd (1),
 253 .IR sd (3),
 254 .IR fs (8),
 255 .IR plan9.ini (8),
 256 .IR prep (8),
 257 .IR venti (8)
 258 .SH SOURCE
 259 .B /sys/src/9/port/devfs.c
 260 .SH BUGS
 261 Mirrors are RAID-like but not RAID.
 262 There is no fancy recovery mechanism and
 263 no automatic initial copying from a master drive to its mirror drives.
 264 .PP
 265 Each
 266 .I write
 267 system call on
 268 .B ctl
 269 may transmit at most one command.