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

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

home | help