Common arguments

Most of the functions accept either a spooldir (a spool directory) or a spoolitem (an item inside the spool directory) argument. A spool directory is a user-created directory, initially empty, which will be accessed by means of the functions defined in this module; otherwise behaviour is undefined. A spool item is the path to an item inside the spool file (including the name of the spool directory itself as prefix).

Workflow

There are three states in which a item inside a spool directory can be:

Temporary

Item file names start with t:. In this state the items are being created.

Zapping

Item file names start with z:. In this state the items are being deleted. There is no way of accessing an item once it was marked for deletion.

Committed

Item file names start with c:. In this state it is supposed that the data in the item will be only read.

Created items (either via spool_mkdir or spool_touch) are initially in a “temporary” state. Items in this state will not be listed by default using spool_items.

Additional states with arbitrary names for spool items can be used. State transitions can be manually done by using spool_state_set. The only thing to care about is not using the t, z and c as custom state names.

spool_make_uid

spool_make_uid

Creates an unique identifier suitable to be used as temporary item in a spool directory. If available, this function uses the uuidgen program (included as part of e2fsprogs), otherwise uses the Bash-supplied $RANDOM variable and the process identifier, which is somewhat weaker, but should work reasonably well.

spool_mkdir

spool_mkdir spooldir

Creates a new temporary directory in the spool directory. Once data in the directory was filled in spool_commit must be applied to it because the directory will be initially marked as temporary.

spool_touch

spool_touch spooldir

Creates a new file in temporary state. Once data gets added to the file spool_commit must be applied to it.

spool_state_get

spool_state_get spoolitem

Obtains the state of a spool item. States are the fierst letters of file names before a colon.

spool_state_set

spool_state_set spoolitem state

Sets the state of an item. The state may be any letter. Note that the implementation of the module already uses t, c and z; remaining letters may be freely used to mark states. Prints the resulting spool item.

spool_commit

spool_commit spoolitem

Commits a spool item. This makes items transition from temporary to commited state. Prints the resulting spool item.

spool_zap

spool_zap spoolitem [ kind ]

Deletes one item from the spool directory.

spool_items

spool_items spooldir [ kind ]

Enumerates items in a spool directory. Spool items are returned as paths to the items including the spool path itself as prefix. Kind may be:

• t for temporary items.
• c for commited items (the default).

spool_cleanup

spool_cleanup spooldir [ kind ]

Cleans up the spool directory. All temporary items and stray in-deletion items will be removed. The latter takes into account the case of an interrupted run of spool_zap.