Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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 ma-
     nipulating 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 std-
	    out. 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 speci-
	    fied  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 speci-
	    fied 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 mod-
     ification	time  (often  maintained by the system). The main difference be-
     tween 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  sta-
     tus  (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 sim-
     ple 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 confirma-
     tion 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mar&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help