FS(3)							 FS(3)

     NAME
	  fs - file system devices

     SYNOPSIS
	  bind -b #k /dev
	  /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 confi-
	  guration strings, it provides	device mirroring, partition-
	  ing, 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
		   from	the files from left to right until one
		   succeeds.  The length of the	mirror device is the
		   minimum 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
		   offset 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
		    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.