.TH FS 1.SH NAMEfs \- file-hierarchy traversal.SH SYNOPSIS.B fs.I verb arg....br.SH DESCRIPTION.B Fsevaluates an expression whose values representthe contents of a hierarchical filesystem.There are six types of value:.TP 10.B fsThe complete contents of a filesystem..TP.B entriesInformation about the entries in a filesystem withouttheir content..TP.B gateA condition that can be used with conditional verbs.A gate is open to entries satisfying particularcriteria..TP.B selectorA comparator which compares two entriesand selects one, both or neither of them..TP.B stringA simple string literal, represented by itself,or quoted according to the usual shell quoting rules..TP.B commandA shell command, represented by an.RB `` @ ''character followed by a braced blockcontaining the shell commands..TP.B voidNo value. An expression of this typecannot be used as an argument to any verb..PPA value is represented either by a literal (a string or shell command),or by a braced block,.BI { verb.RI [ arg ...]\f5}\fP,whose value is the result of evaluating.I verbwith the given arguments..PPIn the following description of the verbs provided,an entry such as:.TP 10.B print \fIentries\fP \fR->\fP void.PPdescribes a verb.BR print ,which takes one argument of type.IR entries ,and the result of which is of type.BR void .If the type is not one of those described above,it should be taken to be of type.IR string ..PPWith no arguments,.I fsprints a summary of the available verbs.Verbs understood by.I fsinclude:.TP 10\f5and\fP \fIgate gate\fP [\fIgate\fP...] -> \fIgate\fP.B Andis a gate that is open to an entry if all its arguments are open..TP\f5bundle\fP \fIfs\fP -> \fIvoid\fP.B Bundleconverts.I fsto an archival format and writes it to the standard output..TP\f5compose\fP [\f5-d\fP] \fIop\fP -> \fIselector\fP.B Composeimplements ``compositing''-style operators, useful whenmerging filesystems..I Opspecifies the operator, taking its name fromthe graphical Porter-Duff equivalent:.BR AinB ,.BR AinB ,.BR BinA ,.BR AoutB ,.BR BoutA ,.BR A ,.BR AoverB ,.BR AatopB ,.BR AxorB ,.BR B ,.BR BoverA ,or.BR BatopA.For instance,.B AinBgives the intersection of A and B;.B AatopBgives A whereever both A and B exist, and B otherwise.When used as a selector for.BR merge ,operators that excludethe union of A and B are not very useful, as they willexclude all common directories at the top level.Given the.B -doption, compose will allow through directories thatwould otherwise be excluded in this way, makingoperators such as.B AxorB(all that A does not hold in common with B)more useful, although accurate only for regular files..TP\f5depth\fP \fIn\fP -> \fIgate\fP.B Depthis a gate open only to entries which are within.I nlevels of the root of the filesystem..TP\f5entries\fP \fIfs\fP -> \fIentries\fP.B Entriesproduces all the entries contained within.IR fs ..TP\f5eval\fP \fIexpr\fP -> \fIany\fP.B Evalevaluates an.I fsexpression and yields its result..TP\f5filter\fP [\f5-d\fP]\fIgate fs\fP -> \fIfs\fPThe result of.B filteris a filesystem from which all entries that willnot pass through.IR gate ,and their descendents, have been removed.If the.B -dflag is given, only files are filtered \- directories bypass the gate..TP\f5ls\fP [\f5-um\fP] \fIentries\fP -> \fIvoid\fPPrint each entry in the style of.B ls -l(see.IR ls (1)).If the.B -uflag is given, the file access time rather than the file modification timewill be printed. If the.B -mflag is given, the name of the user that last modified the fileis printed too..TP\f5exec\fP [\f5-pP\fP] [\f5-t\fP \fIcommand\fP] [\f5-n\fP \fIn\fP] \fIcommand entries\fP -> \fIvoid\fPRun its argument.I commandfor each entry in.I entries .If the.B -nflag is specified,.B execwill try to gather.I nentries together before invoking the command (default 1).The environent variable.B $fileis set to the names of the entries that have been gathered.If the.B -pflag is given, environment variables are set giving informationabout the mode, owner, modification time and size of the entry(they are named after the equivalent fieldnames in the.B Dirstructure; see.IR sys-stat (2)).This option is only valid when.I nis 1.The.B -Pflag causes all the other fields in the Dir structure to be included too.Note that the command is run in the same shell context each time,so environment variable set on one execution canbe retrieved on the next. The.B -tflag can be used to specify a command which will be executedjust before termination..TP\f5match\fP [\f5-ar\fP] \fIpattern\fP -> \fIgate\fP.B Matchis a gate that is open if the entry's filenamematches the.IR pattern .If the.B -aflag is given, the whole path will be usedfor the match.If.B -ris specified, the pattern is evaluated as a regular expression,otherwise it is a shell-style pattern in the style of.IR filepat (2)..TP\f5merge\fP [\f5-1\fP] [\f5-c\fP \fIselector\fP] \fIfs fs\fP [\fIfs\fP...] -> \fIfs\fPRecursively merge the contents of its argumentfilesystems..I Selectoris consulted to see which entries are chosen for the result;if not given, entries are resolved in favour of the first filesystem(equivalent to.BR "{compose AoverB}").If the.B -1flag is given, merging takes place only in the top-level directory..TP\f5mode\fP \fIspec\fP -> \fIgate\fP.B Modeis a gate that lets through entries whose file permissionssatisfy.IR spec ,which is a string in the style of.IR chmod (1).If the.I opfield is.BR + ,the specified permissions must be present; if.BR - ,they must be absent, and if.BR = ,they must be exactly as given.The directory and auth modes are specified withthe characters ``\f5d\fP'' and ``\f5A\fP''respectively..TP\f5not\fP \fIgate\fP -> \fIgate\fP.B Notis a gate open to an entry if its argument is not..TP\f5or\fP \fIgate gate\fP [\fIgate\fP...] -> \fIgate\fP.B Oris a gate open to an entry if any argument is open..TP\f5path\fP [\f5-x\fP] \fIpath\fP... -> \fIgate\fP.B Pathis a gate open to an entry whose full pathnameis an ancestor or a descendent of any.IR path.If.B -xis specified, the gate is open to any path.I exceptdescendents of the paths given..TP\f5pipe\fP [\f5-1pP\fP] \fIcommand fs\fP -> \fIvoid\fP.B Pipeis similar to exec, except that the contents of all filesin.I fsare piped through.IR command .Unless the.B -1option is given,.I commandis started once for each file, with.B $fileset to its name, and other environment variablesset according to the.B -por.B -Poptions, as for.BR exec .If the.B -1option is specified,.I commandis started once only \- all file data is piped through that..TP\f5print\fP \fIentries\fP -> \fIvoid\fPPrint the path name of each entry..TP\f5proto\fP [\f5-r\fP \fIroot\fP] \fIprotofile\fP -> \fIfs\fPEvaluate.I protofileas a.IR mkfs (8).I protofile. If.I rootis specified, it will be used as the root of the resulting.IR fs ..TP\f5query\fP \fIcommand\fP -> \fIgate\fP.B Queryis a gate that runs.I commandto determine whether it is open: an emptyexit status from the command yields an open gate.The environment variable.B $fileis set for the command to the path name of the entry that is being queried for..TP\f5run\fP \fIcommand\fP -> \fIstring\fP.B Runruns.I commandand substitutes the value of the environment variable.B $safter its invocation..B $smust have exactly one element..TP\f5select\fP \fIgate entries\fP -> \fIentries\fPSelect only those entries within.I entriesthat will pass through.IR gate .Descendents of elided entries are not affected..TP\f5setroot\fP [\f5-c\fP] \fIpath\fP \fIfs\fP -> \fIfs\fP.B Setrootsets the name of the root directory of.IR fs .If the.B -cflag is given, the elements in the root directorywill be made explicit in the hierarchy (i.e. thename of the top directory will not contain any.B /characters)..TP\f5size\fP \fIentries\fP -> \fIvoid\fPPrint the sum of the size of all entries, in bytes..TP\f5unbundle\fP \fIfile\fP -> \fIfs\fP.B Unbundlereads an archive as produced by.B bundlefrom.IR file ;its result is the contents of the filesystem that wasoriginally bundled.If.I fileis.IB `` - '',the standard input is read..TP\f5walk\fP \fIpath\fP -> \fIfs\fP.B Walkproduces a filesystem that's the result oftraversing all the files and directories underneath.IR path ..TP\f5write\fP \fIdir fs\fP -> \fIvoid\fPWrite the contents of.I fsto the filesystem rooted at.I dir .If.I diris empty,.I fswill be written to the root directory originally associated with fs..PPAs a convenience,.I fscarries out some automatic type conversions(conversions are applied recursively, so for instance,an.BR fs -valuedexpression at the top level will convertedto void by applying.B {print {entries.IB fs }}\fR..TP.BR string -> fsThe result is \f5{walk\fP \fIstring\f5}\fP..TP.BR fs -> entriesThe result is \f5{entries\fP \fIfs\f5}\fP..TP.BR string -> gateThe result is \f5{match\fP \fIstring\f5}\fP..TP.BR entries -> voidThe result is \f5{print\fP \fIentries\f5}\fP..TP.BR command -> stringThe result is \f5{run\fP \fIcommand\f5}\fP..SH EXAMPLESPrint the size of all files below the current directory:.EX	fs size ..EEShow the names of all files in x that aren't in y:.EX	fs select {mode -d} {merge -c {compose -d AoutB} x y}.EERemove all files from /appl ending in.BR .dis :.EX	fs exec @{rm $file} {select *.dis /appl}.EERecursively copy the current directory to.BR /tmp/foo ..EX	fs bundle . | fs write /tmp/foo {unbundle -}.EEA simpler method of the above:.EX	fs write /tmp/foo ..EEInteractively remove all regular files from one level of the current directory:.IP.EXfs exec @{rm $file} {select {query	@{echo -n $file:; ~ `{read} y yes}}	{select {mode -d} {filter {depth 1} .}}}.EE.PPCreate a new archive containing those files from below the current directorythat were held in an old archive:.EX	fs bundle {merge -c {compose AinB} . {unbundle old.bundle}} > new.bundle.EE.SH SOURCE.B /appl/cmd/fs.b.br.B /appl/cmd/fs/*.b.br.B /appl/lib/fslib.b.SH SEE ALSO.IR sh (1)