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 .B clear
 161 Discard all
 162 .I fs
 163 device definitions.
 164 .PD
 165 .LP
 166 If the variable
 167 .B fsconfig
 168 is set in
 169 .IR plan9.ini (8),
 170 .I fs
 171 will read its configuration from the file
 172 .B $fsconfig
 173 on the first attach.
 174 This is useful when the machine boots from a local file server that uses
 175 .IR fs .
 176 .SH EXAMPLES
 177 Use a previously partitioned disk,
 178 .BR /dev/sdC0 ,
 179 making
 180 partition files available under
 181 .BR /dev/sdC0parts :
 182 .IP
 183 .EX
 184 {
 185         echo disk sdC0parts 512 /dev/sdC0/data
 186         disk/fdisk -p /dev/sdC0/data
 187         # now create plan 9 partitions
 188         echo disk sdC0parts 512 /dev/sdC0parts/plan9
 189         disk/prep -p /dev/sdC0parts/plan9
 190 } > /dev/fs/ctl
 191 .EE
 192 .LP
 193 Mirror the two disks
 194 .B /dev/sdC0/data
 195 and
 196 .B /dev/sdD0/data
 197 as
 198 .BR /dev/fs/m0 ;
 199 similarly, mirror
 200 .B /dev/sdC1/data
 201 and
 202 .B /dev/sdD1/data
 203 as
 204 .BR /dev/fs/m1 :
 205 .IP
 206 .EX
 207 echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/fs/ctl
 208 echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/fs/ctl
 209 .EE
 210 .LP
 211 Interleave the two mirrored disks to create
 212 .BR /dev/fs/data :
 213 .IP
 214 .EX
 215 echo inter data /dev/fs/m0 /dev/fs/m1 >/dev/fs/ctl
 216 .EE
 217 .LP
 218 Run
 219 .IR kfs (4)
 220 on the interleaved device:
 221 .IP
 222 .EX
 223 disk/kfs -f /dev/fs/data
 224 .EE
 225 .LP
 226 Save the configuration:
 227 .IP
 228 .EX
 229 cp /dev/fs/ctl /dev/fd0disk
 230 .EE
 231 .LP
 232 To load the configuration automatically at boot time,
 233 add this to
 234 .IR plan9.ini :
 235 .IP
 236 .EX
 237 fsconfig=/dev/fd0disk
 238 .EE
 239 .SH "SEE ALSO"
 240 .I read
 241 in
 242 .IR cat (1),
 243 .IR dd (1),
 244 .IR sd (3),
 245 .IR fs (8),
 246 .IR plan9.ini (8),
 247 .IR prep (8),
 248 .IR venti (8)
 249 .SH SOURCE
 250 .B /sys/src/9/port/devfs.c
 251 .SH BUGS
 252 Mirrors are RAID-like but not RAID.
 253 There is no fancy recovery mechanism and
 254 no automatic initial copying from a master drive to its mirror drives.
 255 .PP
 256 Each
 257 .I write
 258 system call on
 259 .B ctl
 260 may transmit at most one command.