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.Dd December 31, 2007 29.Dt MTREE 5 30.Os 31.Sh NAME 32.Nm mtree 33.Nd format of mtree dir hierarchy files 34.Sh DESCRIPTION 35The 36.Nm 37format is a textual format that describes a collection of filesystem objects. 38Such files are typically used to create or verify directory hierarchies. 39.Ss General Format 40An 41.Nm 42file consists of a series of lines, each providing information 43about a single filesystem object. 44Leading whitespace is always ignored. 45.Pp 46When encoding file or pathnames, any backslash character or 47character outside of the 95 printable ASCII characters must be 48encoded as a backslash followed by three 49octal digits. 50When reading mtree files, any appearance of a backslash 51followed by three octal digits should be converted into the 52corresponding character. 53.Pp 54Each line is interpreted independently as one of the following types: 55.Bl -tag -width Cm 56.It Signature 57The first line of any mtree file must begin with 58.Dq #mtree . 59If a file contains any full path entries, the first line should 60begin with 61.Dq #mtree v2.0 , 62otherwise, the first line should begin with 63.Dq #mtree v1.0 . 64.It Blank 65Blank lines are ignored. 66.It Comment 67Lines beginning with 68.Cm # 69are ignored. 70.It Special 71Lines beginning with 72.Cm / 73are special commands that influence 74the interpretation of later lines. 75.It Relative 76If the first whitespace-delimited word has no 77.Cm / 78characters, 79it is the name of a file in the current directory. 80Any relative entry that describes a directory changes the 81current directory. 82.It dot-dot 83As a special case, a relative entry with the filename 84.Pa .. 85changes the current directory to the parent directory. 86Options on dot-dot entries are always ignored. 87.It Full 88If the first whitespace-delimited word has a 89.Cm / 90character after 91the first character, it is the pathname of a file relative to the 92starting directory. 93There can be multiple full entries describing the same file. 94.El 95.Pp 96Some tools that process 97.Nm 98files may require that multiple lines describing the same file 99occur consecutively. 100It is not permitted for the same file to be mentioned using 101both a relative and a full file specification. 102.Ss Special commands 103Two special commands are currently defined: 104.Bl -tag -width Cm 105.It Cm /set 106This command defines default values for one or more keywords. 107It is followed on the same line by one or more whitespace-separated 108keyword definitions. 109These definitions apply to all following files that do not specify 110a value for that keyword. 111.It Cm /unset 112This command removes any default value set by a previous 113.Cm /set 114command. 115It is followed on the same line by one or more keywords 116separated by whitespace. 117.El 118.Ss Keywords 119After the filename, a full or relative entry consists of zero 120or more whitespace-separated keyword definitions. 121Each such definitions consists of a key from the following 122list immediately followed by an '=' sign 123and a value. 124Software programs reading mtree files should warn about 125unrecognized keywords. 126.Pp 127Currently supported keywords are as follows: 128.Bl -tag -width Cm 129.It Cm cksum 130The checksum of the file using the default algorithm specified by 131the 132.Xr cksum 1 133utility. 134.It Cm contents 135The full pathname of a file whose contents should be 136compared to the contents of this file. 137.It Cm flags 138The file flags as a symbolic name. 139See 140.Xr chflags 1 141for information on these names. 142If no flags are to be set the string 143.Dq none 144may be used to override the current default. 145.It Cm ignore 146Ignore any file hierarchy below this file. 147.It Cm gid 148The file group as a numeric value. 149.It Cm gname 150The file group as a symbolic name. 151.It Cm md5 152The MD5 message digest of the file. 153.It Cm md5digest 154A synonym for 155.Cm md5 . 156.It Cm sha1 157The 158.Tn FIPS 159160-1 160.Pq Dq Tn SHA-1 161message digest of the file. 162.It Cm sha1digest 163A synonym for 164.Cm sha1 . 165.It Cm sha256 166The 167.Tn FIPS 168180-2 169.Pq Dq Tn SHA-256 170message digest of the file. 171.It Cm sha256digest 172A synonym for 173.Cm sha256 . 174.It Cm ripemd160digest 175The 176.Tn RIPEMD160 177message digest of the file. 178.It Cm rmd160 179A synonym for 180.Cm ripemd160digest . 181.It Cm rmd160digest 182A synonym for 183.Cm ripemd160digest . 184.It Cm mode 185The current file's permissions as a numeric (octal) or symbolic 186value. 187.It Cm nlink 188The number of hard links the file is expected to have. 189.It Cm nochange 190Make sure this file or directory exists but otherwise ignore all attributes. 191.It Cm uid 192The file owner as a numeric value. 193.It Cm uname 194The file owner as a symbolic name. 195.It Cm size 196The size, in bytes, of the file. 197.It Cm link 198The file the symbolic link is expected to reference. 199.It Cm time 200The last modification time of the file, in seconds and nanoseconds. 201The value should include a period character and exactly nine digits 202after the period. 203.It Cm type 204The type of the file; may be set to any one of the following: 205.Pp 206.Bl -tag -width Cm -compact 207.It Cm block 208block special device 209.It Cm char 210character special device 211.It Cm dir 212directory 213.It Cm fifo 214fifo 215.It Cm file 216regular file 217.It Cm link 218symbolic link 219.It Cm socket 220socket 221.El 222.El 223.Sh SEE ALSO 224.Xr cksum 1 , 225.Xr find 1 , 226.Xr mtree 8 227.Sh HISTORY 228The 229.Nm 230utility appeared in 231.Bx 4.3 Reno . 232The 233.Tn MD5 234digest capability was added in 235.Fx 2.1 , 236in response to the widespread use of programs which can spoof 237.Xr cksum 1 . 238The 239.Tn SHA-1 240and 241.Tn RIPEMD160 242digests were added in 243.Fx 4.0 , 244as new attacks have demonstrated weaknesses in 245.Tn MD5 . 246The 247.Tn SHA-256 248digest was added in 249.Fx 6.0 . 250Support for file flags was added in 251.Fx 4.0 , 252and mostly comes from 253.Nx . 254The 255.Dq full 256entry format was added by 257.Nx . 258.Sh BUGS 259The requirement for a 260.Dq #mtree 261signature line is new and not yet widely implemented. 262