XAR(1)								   User Commands							    XAR(1)

NAME

       xar - eXtensible ARchiver

SYNOPSIS

       xar -[ctx][v] ...

DESCRIPTION

       The  XAR  project aims to provide an easily extensible archive format. Important design decisions include an easily extensible XML table of
       contents (TOC) for random access to archived files, storing the TOC at the beginning of the archive to  allow  for  efficient  handling	of
       streamed archives, the ability to handle files of arbitrarily large sizes, the ability to choose independent encodings for individual files
       in the archive, the ability to store checksums for individual files in both compressed and uncompressed form, and the ability to query  the
       table of content's rich meta-data.

FUNCTIONS

       One of the following options must be used:

       -c     Creates an archive

       -t     Lists the contents of an archive

       -x     Extracts an archive

       NOTE: all of the above require the use of the -f option (filename) as this release of xar doesn't correctly handle pipes or sockets.

       -f     The filename to use for creation, listing or extraction.	With extraction, this can be a POSIX regular expression.

OPTIONS

       --compression
	      Specifies the compression type to use.  Valid values: none, gzip, bzip2, lzma.  Default value: gzip

       -C <path>
	      On extract, xar will chdir to the specified path before extracting the archive.

       -a     Synonym for --compression=lzma

       -j     Synonym for --compression=bzip2

       -z     Synonym for --compression=gzip

       --compression-args=<arguments>
	      Specifies  arguments  to	the compression engine selected.  gzip, bzip2, and lzma all take a single integer argument between 0 and 9
	      specifying the compression level to use.

       --dump-toc=<filename>
	      Has xar dump the xml header into the specified file.  "-" can be specified to mean stdout.

       --dump-header
	      Has xar print out the xar binary header information to stdout.

       --extract-subdoc=<name>
	      Extracts the specified subdocument to a document in cwd named <name>.xml

       --list-subdocs
	      List the subdocuments in the xml header

       --toc-cksum
	      Specifies the hashing algorithm to use for xml header verification.  Valid values: none, sha1, and md5.  Default value: sha1

       -l     On archival, stay on the local device.

       -P     On extract, set ownership based on uid/gid.  If the uid/gid can be set on the extracted file, setuid/setgid bits will also  be  pre-
	      served.

       -p     On extract, set ownership based on symbolic names, if possible.  If the uid/gid can be set on the extracted file, setuid/setgid bits
	      will also be preserved.

       -s <filename>
	      On extract, specifies the file to extract subdocuments to.  On archival, specifies an xml file to add as a subdocument.

       -v     Verbose output

       --exclude
	      Specifies a POSIX regular expression of files to exclude from adding to the archive during creation or from being  extracted  during
	      extraction.  This option can be specified multiple times.

       --rsize
	      Specifies a size (in bytes) for the internal libxar read buffer while performing I/O.

       --coalesce-heap
	      When  multiple  files in the archive are identical, only store one copy of the data in the heap.	This creates smaller archives, but
	      the archives created are not streamable.

       --link-same
	      When the data section of multiple files are identical, hardlink them within the archive.

       --no-compress
	      Specifies a POSIX regular expression of files to archive, but not compress.  The archived files will be copied raw into the archive.
	      This can be used to exclude already gzipped files from being gzipped during the archival process.

       --prop-include
	      Specifies  a  file  property  to	be  included  in  the  archive.  When this option is specified, only the specified options will be
	      included.  Anything not specifically included with this option will be omitted.  This option can be used multiple times.

       --prop-exclude
	      Specifies a file property to be excluded from the archive.  When this option is specified, all  file  properties	will  be  included
	      except the specified properties.	This option can be used multiple times.

       --distribution
	      Creates  an archive to only contain file properties safe for file distribution.  Currently, only name, type, mode, and data are pre-
	      served with this option.

       --keep-existing
	      Does not overwrite existing files during extraction.  Keeps any previously existing files while extracting.

       -k     Synonym for --keep-existing.

       --keep-setuid
	      When extracting without -p or -P options, xar will extract files as the uid/gid of the extracting process.  In this  situation,  xar
	      will  strip  setuid/setgid  bits	from the extracted files for security reasons.	--keep-setuid will preserve the setuid/setgid bits
	      even though the uid/gid of the extracted file is not the same as the archived file.

EXAMPLES

       xar -cf sample.xar /home/uid
	      Create a xar archive of all files in /home/uid

       xar -tf sample.xar
	      List the contents of the xar archive sample.xar

       xar -xf sample.xar
	      Extract the contents of sample.xar to the current working directory

BUGS

       Doesn't currently work with pipes or streams.  Might be fixed in a future release.

       Probably one or two more somewhere in there. If you find one please report it to http://code.google.com/p/xar/

AUTHORS

       Rob Braun <bbraun AT synack DOT net>
       Landon Fuller <landonf AT bikemonkey DOT org>
       David Leimbach
       Kevin Van Vechten

version 1.6							 November 1, 2007							    XAR(1)