MTREE(5)                    BSD File Formats Manual                   MTREE(5)

NAME
     mtree - format of mtree dir heirarchy files

DESCRIPTION
     The mtree format is a textual format that describes a col-
     lection of filesystem objects.  Such files are typically
     used to create or verify directory heirarchies.

   General Format
     An mtree file consists of a series of lines, each provid-
     ing 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 con-
     verted into the corresponding character.

     Each line is interpreted independently as one of the fol-
     lowing types:

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

     Blank       Blank lines are ignored.

     Comment     Lines beginning with # are ignored.

     Special     Lines beginning with / are special commands
                 that influence the interpretation of later
                 lines.

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

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

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

     Some tools that process mtree files may require that mul-
     tiple 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:

     /set        This command defines default values for one or
                 more keywords.  It is followed on the same
                 line by one or more whitespace-separated key-
                 word definitions.  These definitions apply to
                 all following files that do not specify a
                 value for that keyword.

     /unset      This command removes any default value set by
                 a previous /set command.  It is followed on
                 the same line by one or more keywords sepa-
                 rated by whitespace.

   Keywords
     After the filename, a full or relative entry consists of
     zero or more whitespace-separated keyword definitions.
     Each such definitions 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:

     cksum       The checksum of the file using the default
                 algorithm specified by the cksum(1) utility.

     contents    The full pathname of a file whose contents
                 should be compared to the contents of this
                 file.

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

     ignore      Ignore any file hierarchy below this file.

     gid         The file group as a numeric value.

     gname       The file group as a symbolic name.

     md5         The MD5 message digest of the file.

     md5digest   A synonym for md5.

     sha1        The FIPS 160-1 (``SHA-1'') message digest of
                 the file.

     sha1digest  A synonym for sha1.

     sha256      The FIPS 180-2 (``SHA-256'') message digest of
                 the file.

     sha256digest
                 A synonym for sha256.

     ripemd160digest
                 The RIPEMD160 message digest of the file.

     rmd160      A synonym for ripemd160digest.

     rmd160digest
                 A synonym for ripemd160digest.

     mode        The current file's permissions as a numeric
                 (octal) or symbolic value.

     nlink       The number of hard links the file is expected
                 to have.

     nochange    Make sure this file or directory exists but
                 otherwise ignore all attributes.

     uid         The file owner as a numeric value.

     uname       The file owner as a symbolic name.

     size        The size, in bytes, of the file.

     link        The file the symbolic link is expected to ref-
                 erence.

     time        The last modification time of the file.

     type        The type of the file; may be set to any one of
                 the following:

                 block       block special device
                 char        character special device
                 dir         directory
                 fifo        fifo
                 file        regular file
                 link        symbolic link
                 socket      socket

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

HISTORY
     The mtree utility appeared in 4.3BSD-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.

BSD                             August 20, 2007                            BSD
