harvey/sys/man/3/fs

.TH FS 3 
.SH NAME
fs \- file system devices
.SH SYNOPSIS
.nf
.B bind -b #k /dev

.B /dev/fs
.B /dev/fs/ctl
.B /dev/fs/...
.fi
.SH DESCRIPTION
The
.I fs
driver builds complex disk files out of simpler disk files. 
Inspired by the Plan 9 file server kernel's configuration strings,
it provides device mirroring, partitioning, interleaving, and catenation
for disk-based services like
.IR kfs (4)
or
.IR venti (8).
.PP
The device
is intended to be bound at
.B /dev
and contains a directory named
.BR fs ,
which in turn contains a
.B ctl
file and one file per configured device.
.PP
Most control messages each introduce a new device, here named
.IR new .
The
.I file
arguments are interpreted in the name space of the writer.
.TP
.BI cat " new files" \fR...
The device
.I new
corresponds to the catenation of
.IR files .
.TP
.BI inter " new files" \fR...
The device
.I new
corresponds to the block interleaving of
.IR files ;
an 8192-byte block size is assumed.
.TP
.BI mirror " new files" \fR...
The device
.I new
corresponds to a RAID-1-like mirroring of
.IR files .
Writes to
.BI new
are handled by sequentially writing the same data to the
.I files
from right to left (the reverse of
the order in the control 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
.BI new
are handled by sequentially reading from the
.I files
from left to right until one succeeds.
The length of the mirror device is the minimum of the lengths of the 
.IR files .
.TP
.BI part " new file offset length"
The device
.I new
corresponds to the
.I length
bytes starting at
.I offset
in
.IR file .
If
.IR offset + length
reaches past the end of
.IR file ,
.I length
is silently reduced to fit.
.TP
.B clear
Discard all
.I fs
device definitions.
.PD
.LP
If the variable
.B fsconfig
is set in
.IR plan9.ini (8)
then 
.I fs
will read its configuration from the file
.B $fsconfig
on the first attach.
This is useful when the machine boots
from a local file server that uses
.IR fs .
.SH EXAMPLE
Mirror the two disks
.B /dev/sdC0/data
and
.B /dev/sdD0/data
as
.BR /dev/fs/m0 ;
similarly, mirror
.B /dev/sdC1/data
and
.B /dev/sdD1/data
as
.BR /dev/fs/m1 :
.IP
.EX
echo mirror m0 /dev/sdC0/data /dev/sdD0/data >/dev/fs/ctl
echo mirror m1 /dev/sdC1/data /dev/sdD1/data >/dev/fs/ctl
.EE
.LP
Interleave the two mirrored disks to create
.BR /dev/fs/data :
.IP
.EX
echo inter data /dev/fs/m0 /dev/fs/m1 >/dev/fs/ctl
.EE
.LP
Run
.IR kfs (4)
on the interleaved device:
.IP
.EX
disk/kfs -f /dev/fs/data
.EE
.LP
Save the configuration:
.IP
.EX
cp /dev/fs/ctl /dev/fd0disk
.EE
.LP
To load the configuration automatically at boot time,
add this to
.IR plan9.ini :
.IP
.EX
fsconfig=/dev/fd0disk
.EE
.SH "SEE ALSO"
.I read
in
.IR cat (1),
.IR dd (1),
.IR sd (3),
.IR kfs (4),
.IR fs (8),
.IR plan9.ini (8),
.IR prep (8),
.IR venti (8)
.SH SOURCE
.B /sys/src/9/port/devfs.c
.SH 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.
.PP
Each
.I write
system call on
.B ctl
may transmit at most one command.