mar - utility for manipulating mar files
utility uses the mar
library to provide a convenient tool
for manipulating mar
files from the command prompt.
Do not prompt for confirmation when using one of the following delete-like
operations; -r, -u or -z.
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.
List the key for each meta item contained within the archive to stdout. Each
of the resulting keys will be followed by a newline.
Print the total length (in bytes) of the user data stored within the archive
- -m key
Given the key for a meta item, print the associated meta data to
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
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.
Zero truncate (delete) the entire contents of the user data section from the
archive. Use the -f option to suppress the confirmation prompt.
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.
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.
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
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
Written by Mark Aylett.
Report bugs to <firstname.lastname@example.org>.