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