A persistent file system (see Section sec-fist-type-persistent) needs to store state in an auxiliary file system. The information stored needs to be formatted to fit off-line storage. For example, it must not contain pointers that may be valid in memory at the moment, but are certainly invalid after a reboot. In addition, facilities are needed for describing what information is stored in the state file system, and in what format it is stored.
State is defined by assigning a key and optional value to the FiST %state function. FiST knows when state needs to be actually flushed to permanent storage. It knows when you are assigning to it (writing state), or reading from it. The syntax for setting a state is as follows: %state op, keylist, valuelist where op is an operation to perform on the state. It can be one of add, del, overwrite, addunique, etc. I.e., normal data structure lookup table operations one might expect. The parameter keylist is a list of one or more keys and valuelist includes zero or more values.
The overall key is stored using a concatenation of the values of the keys; since no pointers are allowed, if any are specified, they would have to first be followed until their value is reached. No effort will be attempted to follow arbitrarily complex pointers.
The overall value stored is the list of concatenated values. Each value is preceded by the number of bytes stored. A valueless key has a zero byte count. The whole sequence is preceded by the number of items stored. If no values are specified, the number of items stored is set to zero.
The syntax for reading values from Statefs is as follows: %state op, keylist where op is get, and keylist is the same as when writing state. If the entry does not exist, the operation will return the error code ENOENT (``no such entry''). If it is empty, a non-zero integer will be returned. Otherwise, the list of values will be returned into the same type variables as were assigned to when the state was written.