MAR(1) User Commands MAR(1)NAMEmar - utility for manipulating mar files
SYNOPSISmar 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 new‐
line.
-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 ar‐
chive. 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 sin‐
gle 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 file‐
name 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 sec‐
tion from the archive. Use the -f option to suppress the confir‐
mation 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 inte‐
gral 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 arbi‐
trary 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 con‐
firmation 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>.
mar 0.5 December 2004 MAR(1)
