FS(3)                                                       FS(3)

     NAME
          fs - file system devices

     SYNOPSIS
          bind -b #k /dev
9          /dev/fs
          /dev/fs/ctl
          /dev/fs/...
          /dev/new

     DESCRIPTION
          The fs driver builds complex disk files out of simpler disk
          files.  Inspired by the Plan 9 file server kernel's configu-
          ration strings, it provides device mirroring, partitioning,
          interleaving, and catenation for disk-based services like
          venti(8).

          The device is intended to be bound at /dev and initially
          contains a directory named fs, which in turn contains a ctl
          file and one file per configured device.

          Most control messages introduce a new device, here named
          new. The file arguments are interpreted in the name space of
          the writing process.

          The device name new may be a single filename component (con-
          taining no slashes); in this case, the device is created
          under #k/fs.  If new instead has the format dir/file, the
          device is made available at #k/dir/file.  The directory dir
          goes away when the last device on it is removed with the del
          control message, but #k/fs will never be removed.

          cat new files...
                   The device new corresponds to the catenation of
                   files.

          inter new files...
                   The device new corresponds to the block interleav-
                   ing of files; an 8192-byte block size is assumed.

          mirror new files...
                   The device new corresponds to a RAID-1-like mirror-
                   ing of files. Writes to new are handled by sequen-
                   tially writing the same data to the files from
                   right to left (the reverse of the order in the con-
                   trol message).  A failed write causes an eventual
                   error return but does not prevent the rest of the
                   writes to the other devices of the mirror set.
                   Reads from new are handled by sequentially reading

9     Page 1                       Plan 9             (printed 3/28/24)

     FS(3)                                                       FS(3)

                   from the files from left to right until one suc-
                   ceeds.  The length of the mirror device is the min-
                   imum of the lengths of the files.

          part new file offset length

          part new offset end
                   In the first form, the device new corresponds to
                   the length units starting at offset in file. If
                   offset+length reaches past the end of file, length
                   is silently reduced to fit.  Units are bytes.  In
                   the second form, a previous disk request must have
                   defined the source file for further requests and
                   the end of the device is determined by the end off-
                   set in the source file, and not by the device
                   length. Units are as defined in the previous disk
                   request. This form is accepted for compatibility
                   with fdisk (in prep(8)) and sd(3) devices.

          del old  Removes the device named old. The device will still
                   be seen while in use.  Further I/O attempts will
                   fail with an error indication stating that the
                   device is gone.  When old is dir/*, all devices
                   under dir are removed.

          disk dir [ n file ]
                   makes dir implicit in new device names (i.e., it
                   makes new mean dir/new by default).  Optional argu-
                   ment n specifies the default unit (sector) size in
                   bytes and the default source file for further par-
                   tition devices.  Default values are restored when
                   the control file is closed.

          crypt new file key
                   The device new corresponds to a AES-encrypted par-
                   tition file encrypted with key (see cryptsetup(8)).

          clear    Discard all fs device definitions.

          If the variable fsconfig is set in plan9.ini(8), fs will
          read its configuration from the file $fsconfig on the first
          attach.  This is useful when the machine boots from a local
          file server that uses fs.

     EXAMPLES
          Use a previously partitioned disk, /dev/sdC0, making parti-
          tion files available under /dev/sdC0parts:

               {
                    echo disk sdC0parts 512 /dev/sdC0/data
                    disk/fdisk -p /dev/sdC0/data
                    # now create plan 9 partitions

     Page 2                       Plan 9             (printed 3/28/24)

     FS(3)                                                       FS(3)

                    echo disk sdC0parts 512 /dev/sdC0parts/plan9
                    disk/prep -p /dev/sdC0parts/plan9
               } > /dev/fs/ctl

          Mirror the two disks /dev/sdC0/data and /dev/sdD0/data as
          /dev/fs/m0; similarly, mirror /dev/sdC1/data and
          /dev/sdD1/data as /dev/fs/m1:

               echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/fs/ctl
               echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/fs/ctl

          Interleave the two mirrored disks to create /dev/fs/data:

               echo inter data /dev/fs/m0 /dev/fs/m1 >/dev/fs/ctl

          Run hjfs(4) on the interleaved device:

               hjfs -f /dev/fs/data

          Save the configuration:

               cp /dev/fs/ctl /dev/fd0disk

          To load the configuration automatically at boot time, add
          this to plan9.ini:

               fsconfig=/dev/fd0disk

     SEE ALSO
          read in cat(1), dd(1), sd(3), fs(8), plan9.ini(8), prep(8),
          venti(8)

     SOURCE
          /sys/src/9/port/devfs.c

     BUGS
          Mirrors are RAID-like but not RAID.  There is no fancy
          recovery mechanism and no automatic initial copying from a
          master drive to its mirror drives.

          Each write system call on ctl may transmit at most one com-
          mand.

     Page 3                       Plan 9             (printed 3/28/24)