1.\" Copyright (c) 1989, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93 29.\" 30.Dd December 31, 2007 31.Dt MTREE 5 32.Os 33.Sh NAME 34.Nm mtree 35.Nd format of mtree dir hierarchy files 36.Sh DESCRIPTION 37The 38.Nm 39format is a textual format that describes a collection of filesystem objects. 40Such files are typically used to create or verify directory hierarchies. 41.Ss General Format 42An 43.Nm 44file consists of a series of lines, each providing information 45about a single filesystem object. 46Leading whitespace is always ignored. 47.Pp 48When encoding file or pathnames, any backslash character or 49character outside of the 95 printable ASCII characters must be 50encoded as a backslash followed by three 51octal digits. 52When reading mtree files, any appearance of a backslash 53followed by three octal digits should be converted into the 54corresponding character. 55.Pp 56Each line is interpreted independently as one of the following types: 57.Bl -tag -width Cm 58.It Signature 59The first line of any mtree file must begin with 60.Dq #mtree . 61If a file contains any full path entries, the first line should 62begin with 63.Dq #mtree v2.0 , 64otherwise, the first line should begin with 65.Dq #mtree v1.0 . 66.It Blank 67Blank lines are ignored. 68.It Comment 69Lines beginning with 70.Cm # 71are ignored. 72.It Special 73Lines beginning with 74.Cm / 75are special commands that influence 76the interpretation of later lines. 77.It Relative 78If the first whitespace-delimited word has no 79.Cm / 80characters, 81it is the name of a file in the current directory. 82Any relative entry that describes a directory changes the 83current directory. 84.It dot-dot 85As a special case, a relative entry with the filename 86.Pa .. 87changes the current directory to the parent directory. 88Options on dot-dot entries are always ignored. 89.It Full 90If the first whitespace-delimited word has a 91.Cm / 92character after 93the first character, it is the pathname of a file relative to the 94starting directory. 95There can be multiple full entries describing the same file. 96.El 97.Pp 98Some tools that process 99.Nm 100files may require that multiple lines describing the same file 101occur consecutively. 102It is not permitted for the same file to be mentioned using 103both a relative and a full file specification. 104.Ss Special commands 105Two special commands are currently defined: 106.Bl -tag -width Cm 107.It Cm /set 108This command defines default values for one or more keywords. 109It is followed on the same line by one or more whitespace-separated 110keyword definitions. 111These definitions apply to all following files that do not specify 112a value for that keyword. 113.It Cm /unset 114This command removes any default value set by a previous 115.Cm /set 116command. 117It is followed on the same line by one or more keywords 118separated by whitespace. 119.El 120.Ss Keywords 121After the filename, a full or relative entry consists of zero 122or more whitespace-separated keyword definitions. 123Each such definitions consists of a key from the following 124list immediately followed by an '=' sign 125and a value. 126Software programs reading mtree files should warn about 127unrecognized keywords. 128.Pp 129Currently supported keywords are as follows: 130.Bl -tag -width Cm 131.It Cm cksum 132The checksum of the file using the default algorithm specified by 133the 134.Xr cksum 1 135utility. 136.It Cm contents 137The full pathname of a file whose contents should be 138compared to the contents of this file. 139.It Cm flags 140The file flags as a symbolic name. 141See 142.Xr chflags 1 143for information on these names. 144If no flags are to be set the string 145.Dq none 146may be used to override the current default. 147.It Cm ignore 148Ignore any file hierarchy below this file. 149.It Cm gid 150The file group as a numeric value. 151.It Cm gname 152The file group as a symbolic name. 153.It Cm md5 154The MD5 message digest of the file. 155.It Cm md5digest 156A synonym for 157.Cm md5 . 158.It Cm sha1 159The 160.Tn FIPS 161160-1 162.Pq Dq Tn SHA-1 163message digest of the file. 164.It Cm sha1digest 165A synonym for 166.Cm sha1 . 167.It Cm sha256 168The 169.Tn FIPS 170180-2 171.Pq Dq Tn SHA-256 172message digest of the file. 173.It Cm sha256digest 174A synonym for 175.Cm sha256 . 176.It Cm ripemd160digest 177The 178.Tn RIPEMD160 179message digest of the file. 180.It Cm rmd160 181A synonym for 182.Cm ripemd160digest . 183.It Cm rmd160digest 184A synonym for 185.Cm ripemd160digest . 186.It Cm mode 187The current file's permissions as a numeric (octal) or symbolic 188value. 189.It Cm nlink 190The number of hard links the file is expected to have. 191.It Cm nochange 192Make sure this file or directory exists but otherwise ignore all attributes. 193.It Cm uid 194The file owner as a numeric value. 195.It Cm uname 196The file owner as a symbolic name. 197.It Cm size 198The size, in bytes, of the file. 199.It Cm link 200The file the symbolic link is expected to reference. 201.It Cm time 202The last modification time of the file, in seconds and nanoseconds. 203The value should include a period character and exactly nine digits 204after the period. 205.It Cm type 206The type of the file; may be set to any one of the following: 207.Pp 208.Bl -tag -width Cm -compact 209.It Cm block 210block special device 211.It Cm char 212character special device 213.It Cm dir 214directory 215.It Cm fifo 216fifo 217.It Cm file 218regular file 219.It Cm link 220symbolic link 221.It Cm socket 222socket 223.El 224.El 225.Sh SEE ALSO 226.Xr cksum 1 , 227.Xr find 1 , 228.Xr mtree 8 229.Sh HISTORY 230The 231.Nm 232utility appeared in 233.Bx 4.3 Reno . 234The 235.Tn MD5 236digest capability was added in 237.Fx 2.1 , 238in response to the widespread use of programs which can spoof 239.Xr cksum 1 . 240The 241.Tn SHA-1 242and 243.Tn RIPEMD160 244digests were added in 245.Fx 4.0 , 246as new attacks have demonstrated weaknesses in 247.Tn MD5 . 248The 249.Tn SHA-256 250digest was added in 251.Fx 6.0 . 252Support for file flags was added in 253.Fx 4.0 , 254and mostly comes from 255.Nx . 256The 257.Dq full 258entry format was added by 259.Nx . 260.Sh BUGS 261The requirement for a 262.Dq #mtree 263signature line is new and not yet widely implemented. 264