NAME

mar - utility for manipulating mar files

SYNOPSIS

mar option... archive

DESCRIPTION

The mar utility uses the mar library to provide a convenient tool for manipulating mar files from the command prompt.

OPTIONS

-f

Do not prompt for confirmation when using one of the following delete-like operations; -r, -u or -z.

-h

Display a brief help summary and then exit.

-i filename

Insert the contents of the file specified by filename into the user data section of the archive. If the filename specified is "-" then stdin will be used as the input stream.

-k

List the key for each meta item contained within the archive to stdout. Each of the resulting keys will be followed by a newline.

-l

Print the total length (in bytes) of the user data stored within the archive to stdout.

-m key

Given the key for a meta item, print the associated meta data to stdout.

-r

Remove (delete) all meta items (including keys) from the archive. Use the -f option to suppress the confirmation prompt.

-s source

Meta items are set by specifying one of more key/data pairs. Each key/data pair should be specified in the format; key=data, where the key and data part of the pair are delimited using the "=" character. Any whitespace characters occurring either side of the delimiter are significant and will not therefore be stripped when the pair is split. The source can either be a single key/data pair specified on the command line or a filename. If a filename is specified then key/data pairs will be read (one pair per line) from the file specified by filename. If the filename specified is "-" then stdin will be used as the input stream.

-t

List each meta item contained within the archive to stdout. Each meta item is displayed as a key/data pair in the format; key=data, where the key and data part of the pair are delimited using the "=" character. Each key/data pair will be followed by a newline.

-u key

Unset (delete) the meta item specified by key from the archive. Use the -f option to suppress the confirmation prompt.

-x filename

Extract (a copy of) the contents of the user data section from the archive into the file specified by filename. If the filename specified is "-" then stdout will be used as the output stream.

-z

Zero truncate (delete) the entire contents of the user data section from the archive. Use the -f option to suppress the confirmation prompt.

OVERVIEW

A meta archive or mar file uses a simple binary file format to store both meta and user data together in a single file. User data in this context is akin to the type of data traditionally stored by a user in a regular file. Text or image information would be typical examples of user data. Meta data is that information relating to, but not an integral part of, the user data. The location at which an image (user data) was captured would be an example of an item of meta data. Depending on the type of file system, most regular files already contain some built-in meta data such as the file modification time (often maintained by the system). The main difference between the meta data found in a mar file and that of a regular file is that the mar file allows an arbitrary set of meta data to be defined by a user or application of which the underlying file system has no knowledge.

A mar file may be suitable in situations where a full-scale database is not. Taking the example of an e-mail message, if an item of meta data such as the "read/unread" message status is stored in an auxiliary file (away from the actual message to which it relates), then the task of ensuring the integrity of both files may quickly lead to a more complex system than had been originally intended. Using a mar file, the "read/unread" message status (the meta data) would be stored in the same file as the actual message content (the user data), therefore offering the possibility of using a simple swap-file idiom to ensure data integrity.

EXAMPLES

Insert the contents of "input.txt" into the user data section of the archive and then print the number of bytes stored to stdout:

    mar -i input.txt -l archive.mar

Extract (a copy of) the contents of the user data section to stdout and then zero truncate the contents without prompting for confirmation:

    mar -x - -f -z archive.mar

Set two meta items (with keys "familyname" and "givenname") and then list all meta data pairs to stdout:

    mar -s familyname=Aylett -s givenname=Mark -t archive.mar

Unset the meta item (with key "familyname") without prompting for confirmation and then list all remaining keys names within the archive to stdout:

    mar -f -u familyname -k archive.mar

Print the meta data (for the item with key "givenname") to stdout and then remove (delete) all meta items without prompting for confirmation:

    mar -m givenname -f -r archive.mar

AUTHOR

Written by Mark Aylett.

REPORTING BUGS

Report bugs to <mark@emantic.co.uk>.