MAR(1)				 User Commands				MAR(1)

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  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)

Vote for polarhome