4.8.3 Rules

Filters are a construct that is useful when a ``stream'' of data needs to be modified the way Unix filters do. FiST Filters are just a specialization of the more general construct -- Rules. FiST Rules allow finer and more flexible control over errors, arguments, and even data. Rules can access global data, where filters may not.

Rules for vnode operations take precedence over the filter definition of a vnode function. Each rule has the form of a FiST operation, followed by a single colon, optional action code, and terminated with a semicolon: fistop: action ; where fistop is a name of a vnode/VFS operation, optionally prefixed by a file system index variable and separated by a single dot. For example:

• vfs_root refers to the ``get root vnode'' VFS operation of the first and only interposed file system.

• $1.vfs_root refers to the same operation on the first interposed file system, when there are two or more interposed file systems.

• $2.vn_getattr refers to the vnode ``get attributes'' operation on the second interposed file system.

• $0.vn_mkdir refers to the vnode ``make directory'' operation on the state-storing interposed file system of a persistent file system.

• $$.vn_setattr.error_action refers to the error action code section of the vnode ``set attributes operation of the current vnode. See Tables tab-fist-code-var-stateless and tab-fist-code-var-persistent.

  

Figure: FiST Default Rule Action for Stateless and In-Core File Systems (Pseudo-Code)

3.9in

Figure: FiST Default Rule Action for Stateless and In-Core File Systems (Pseudo-Code)

define variables -- optional
manipulate the incoming arguments vector -- optional
foreach f in all interposers of this file system
do
error = $f.fistop(args);
if (error == ERROR); then
perform actions based on errors -- optional
return error;
endif
manipulate the returning arguments vector -- optional
done

3.65in

define variables -- optional
manipulate the incoming arguments vector -- optional
foreach f in all interposers of this file system
do
error = $f.fistop(args);
if (error == ERROR); then
perform actions based on errors -- optional
return error;
endif
manipulate the returning arguments vector -- optional
done

The optional action code, if included, must be delimited by a set of curly braces {...}. If the action is omitted, the default action is used. The pseudo-code for the default action for stateless and in-core FiST file systems is depicted in Figure fig-fist-action-incore, while pseudo-code for the default action for persistent file systems is shown in Figure fig-fist-action-persistent.

FiST allows the file system designer to control each portion of the default code for stateless and in-core file systems. Keywords for each section are listed in Table tab-fist-code-var-stateless.

 

Table: Code Section Names for Stateless and In-Core File Systems

Keyword	Code Section
%variables	define local variables
%in_args	manipulate the incoming arguments vector
%error_action	perform actions based on errors
%out_args	manipulate the returning arguments vector

 

  

Figure: FiST Default Rule Action for Persistent File Systems (Pseudo-Code)

Figure: FiST Default Rule Action for Persistent File Systems (Pseudo-Code)

define variables -- optional
lock this vnode and all vnodes in the interposition chain.
manipulate the incoming arguments vector -- optional
foreach f in all interposers of this file system ; do
retval[f] = $f.fistop(args);
manipulate the returning arguments vector -- optional
done
if any error occurred ; then
perform actions based on errors -- optional
unlock interposition chain (and possibly unroll action).
return error ;
endif
save any state defined on $0.
final manipulation of return codes
unlock interposition chain.
return status-code ;

3.65in

define variables -- optional
lock this vnode and all vnodes in the interposition chain.
manipulate the incoming arguments vector -- optional
foreach f in all interposers of this file system ; do
retval[f] = $f.fistop(args);
manipulate the returning arguments vector -- optional
done
if any error occurred ; then
perform actions based on errors -- optional
unlock interposition chain (and possibly unroll action).
return error ;
endif
save any state defined on $0.
final manipulation of return codes
unlock interposition chain.
return status-code ;

FiST also lets the file system designer to control each portion of the default code for persistent file systems. Keywords for each section are listed in Table tab-fist-code-var-persistent.

 

Table: Code Section Names for Persistent File Systems

Keyword	Code Section
%variables	define local variables
%in_args	manipulate the incoming arguments vector
%action	retval[f] = $f.fistop(args);
%out_args	manipulate the returning arguments vector
%error_action	perform actions based on errors
%out_state	save any state defined
%out_error	final manipulation of return codes

 

The code is treated as normal C code, but certain special variables and functions are interpreted and expanded at code generation time. The variables that are specially expanded are the positional variables $$, $0, $1, $2, $3, etc. Special functions that are available would include all filter functions defined above:

• functions to access the state file system (write state, read state, lookup state, etc.)

• functions to run a filter on data (de/compress, encrypt/decrypt)

• functions to manipulate pathnames (expand, translate)

• functions to manipulate user credentials and file modes

• error handling when using more than one interposed file system (fail first, run through the end and return worst failure, restart operation on error, number of retries, etc.)