path: root/archivers/libarchive/files/doc/wiki/ManPageMtree5.wiki

#summary MTREE 5 manual page
== NAME ==
*mtree*
- format of mtree dir hierarchy files
== DESCRIPTION ==
The
*mtree*
format is a textual format that describes a collection of filesystem objects.
Such files are typically used to create or verify directory hierarchies.
=== General Format===
An
*mtree*
file consists of a series of lines, each providing information
about a single filesystem object.
Leading whitespace is always ignored.

When encoding file or pathnames, any backslash character or
character outside of the 95 printable ASCII characters must be
encoded as a a backslash followed by three
octal digits.
When reading mtree files, any appearance of a backslash
followed by three octal digits should be converted into the
corresponding character.

Each line is interpreted independently as one of the following types:
<dl>
<dt>Signature</dt><dd>
The first line of any mtree file must begin with
"#mtree".
If a file contains any full path entries, the first line should
begin with
"#mtree v2.0",
otherwise, the first line should begin with
"#mtree v1.0".
</dd><dt>Blank</dt><dd>
Blank lines are ignored.
</dd><dt>Comment</dt><dd>
Lines beginning with
*#*
are ignored.
</dd><dt>Special</dt><dd>
Lines beginning with
*/*
are special commands that influence
the interpretation of later lines.
</dd><dt>Relative</dt><dd>
If the first whitespace-delimited word has no
*/*
characters,
it is the name of a file in the current directory.
Any relative entry that describes a directory changes the
current directory.
</dd><dt>dot-dot</dt><dd>
As a special case, a relative entry with the filename
_.._
changes the current directory to the parent directory.
Options on dot-dot entries are always ignored.
</dd><dt>Full</dt><dd>
If the first whitespace-delimited word has a
*/*
character after
the first character, it is the pathname of a file relative to the
starting directory.
There can be multiple full entries describing the same file.
</dd></dl>

Some tools that process
*mtree*
files may require that multiple lines describing the same file
occur consecutively.
It is not permitted for the same file to be mentioned using
both a relative and a full file specification.
=== Special commands===
Two special commands are currently defined:
<dl>
<dt>*/set*</dt><dd>
This command defines default values for one or more keywords.
It is followed on the same line by one or more whitespace-separated
keyword definitions.
These definitions apply to all following files that do not specify
a value for that keyword.
</dd><dt>*/unset*</dt><dd>
This command removes any default value set by a previous
*/set*
command.
It is followed on the same line by one or more keywords
separated by whitespace.
</dd></dl>
=== Keywords===
After the filename, a full or relative entry consists of zero
or more whitespace-separated keyword definitions.
Each such definition consists of a key from the following
list immediately followed by an '=' sign
and a value.
Software programs reading mtree files should warn about
unrecognized keywords.

Currently supported keywords are as follows:
<dl>
<dt>*cksum*</dt><dd>
The checksum of the file using the default algorithm specified by
the
*cksum*(1)
utility.
</dd><dt>*contents*</dt><dd>
The full pathname of a file that holds the contents of this file.
</dd><dt>*flags*</dt><dd>
The file flags as a symbolic name.
See
*chflags*(1)
for information on these names.
If no flags are to be set the string
"none"
may be used to override the current default.
</dd><dt>*gid*</dt><dd>
The file group as a numeric value.
</dd><dt>*gname*</dt><dd>
The file group as a symbolic name.
</dd><dt>*ignore*</dt><dd>
Ignore any file hierarchy below this file.
</dd><dt>*link*</dt><dd>
The target of the symbolic link when type=link.
</dd><dt>*md5*</dt><dd>
The MD5 message digest of the file.
</dd><dt>*md5digest*</dt><dd>
A synonym for
*md5*.
</dd><dt>*mode*</dt><dd>
The current file's permissions as a numeric (octal) or symbolic
value.
</dd><dt>*nlink*</dt><dd>
The number of hard links the file is expected to have.
</dd><dt>*nochange*</dt><dd>
Make sure this file or directory exists but otherwise ignore all attributes.
</dd><dt>*ripemd160digest*</dt><dd>
The
*RIPEMD160*
message digest of the file.
</dd><dt>*rmd160*</dt><dd>
A synonym for
*ripemd160digest*.
</dd><dt>*rmd160digest*</dt><dd>
A synonym for
*ripemd160digest*.
</dd><dt>*sha1*</dt><dd>
The
*FIPS*
160-1
("Tn SHA-1")
message digest of the file.
</dd><dt>*sha1digest*</dt><dd>
A synonym for
*sha1*.
</dd><dt>*sha256*</dt><dd>
The
*FIPS*
180-2
("Tn SHA-256")
message digest of the file.
</dd><dt>*sha256digest*</dt><dd>
A synonym for
*sha256*.
</dd><dt>*size*</dt><dd>
The size, in bytes, of the file.
</dd><dt>*time*</dt><dd>
The last modification time of the file.
</dd><dt>*type*</dt><dd>
The type of the file; may be set to any one of the following:

<dl>
<dt>*block*</dt><dd>
block special device
</dd><dt>*char*</dt><dd>
character special device
</dd><dt>*dir*</dt><dd>
directory
</dd><dt>*fifo*</dt><dd>
fifo
</dd><dt>*file*</dt><dd>
regular file
</dd><dt>*link*</dt><dd>
symbolic link
</dd><dt>*socket*</dt><dd>
socket
</dd></dl>
</dd><dt>*uid*</dt><dd>
The file owner as a numeric value.
</dd><dt>*uname*</dt><dd>
The file owner as a symbolic name.
</dd></dl>

== SEE ALSO ==
*cksum*(1),
*find*(1),
*mtree*(8)
== BUGS ==
The
FreeBSD
implementation of mtree does not currently support
the
*mtree*
2.0
format.
The requirement for a
"#mtree"
signature line is new and not yet widely implemented.
== HISTORY ==
The
*mtree*
utility appeared in
BSD 4.3 Reno.
The
*MD5*
digest capability was added in
FreeBSD 2.1,
in response to the widespread use of programs which can spoof
*cksum*(1).
The
*SHA-1*
and
*RIPEMD160*
digests were added in
FreeBSD 4.0,
as new attacks have demonstrated weaknesses in
*MD5 .*
The
*SHA-256*
digest was added in
FreeBSD 6.0.
Support for file flags was added in
FreeBSD 4.0,
and mostly comes from
NetBSD.
The
"full"
entry format was added by
NetBSD.