DragonFly On-Line Manual Pages

Search: Section:  

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

mar 0.5                          December 2004                          MAR(1)

Search: Section: