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.\" 30.Dd September 4, 2013 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 Blank 59Blank lines are ignored. 60.It Comment 61Lines beginning with 62.Cm # 63are ignored. 64.It Special 65Lines beginning with 66.Cm / 67are special commands that influence 68the interpretation of later lines. 69.It Relative 70If the first whitespace-delimited word has no 71.Cm / 72characters, 73it is the name of a file in the current directory. 74Any relative entry that describes a directory changes the 75current directory. 76.It dot-dot 77As a special case, a relative entry with the filename 78.Pa .. 79changes the current directory to the parent directory. 80Options on dot-dot entries are always ignored. 81.It Full 82If the first whitespace-delimited word has a 83.Cm / 84character after 85the first character, it is the pathname of a file relative to the 86starting directory. 87There can be multiple full entries describing the same file. 88.El 89.Pp 90Some tools that process 91.Nm 92files may require that multiple lines describing the same file 93occur consecutively. 94It is not permitted for the same file to be mentioned using 95both a relative and a full file specification. 96.Ss Special commands 97Two special commands are currently defined: 98.Bl -tag -width Cm 99.It Cm /set 100This command defines default values for one or more keywords. 101It is followed on the same line by one or more whitespace-separated 102keyword definitions. 103These definitions apply to all following files that do not specify 104a value for that keyword. 105.It Cm /unset 106This command removes any default value set by a previous 107.Cm /set 108command. 109It is followed on the same line by one or more keywords 110separated by whitespace. 111.El 112.Ss Keywords 113After the filename, a full or relative entry consists of zero 114or more whitespace-separated keyword definitions. 115Each such definition consists of a key from the following 116list immediately followed by an '=' sign 117and a value. 118Software programs reading mtree files should warn about 119unrecognized keywords. 120.Pp 121Currently supported keywords are as follows: 122.Bl -tag -width Cm 123.It Cm cksum 124The checksum of the file using the default algorithm specified by 125the 126.Xr cksum 1 127utility. 128.It Cm device 129The device number for 130.Sy block 131or 132.Sy char 133file types. 134The value must be one of the following forms: 135.Bl -tag -width 4n 136.It Ar format , Ns Ar major , Ns Ar minor Ns Bo , Ns Ar subunit Bc 137A device with 138.Ar major , minor 139and optional 140.Ar subunit 141fields. 142Their meaning is specified by the operating's system 143.Ar format . 144See below for valid formats. 145.It Ar number 146Opaque number (as stored on the file system). 147.El 148.Pp 149The following values for 150.Ar format 151are recognized: 152.Sy native , 153.Sy 386bsd , 154.Sy 4bsd , 155.Sy bsdos , 156.Sy freebsd , 157.Sy hpux , 158.Sy isc , 159.Sy linux , 160.Sy netbsd , 161.Sy osf1 , 162.Sy sco , 163.Sy solaris , 164.Sy sunos , 165.Sy svr3 , 166.Sy svr4 , 167and 168.Sy ultrix . 169.Pp 170See 171.Xr mknod 8 172for more details. 173.It Cm contents 174The full pathname of a file that holds the contents of this file. 175.It Cm flags 176The file flags as a symbolic name. 177See 178.Xr chflags 1 179for information on these names. 180If no flags are to be set the string 181.Dq none 182may be used to override the current default. 183.It Cm gid 184The file group as a numeric value. 185.It Cm gname 186The file group as a symbolic name. 187.It Cm ignore 188Ignore any file hierarchy below this file. 189.It Cm inode 190The inode number. 191.It Cm link 192The target of the symbolic link when type=link. 193.It Cm md5 194The MD5 message digest of the file. 195.It Cm md5digest 196A synonym for 197.Cm md5 . 198.It Cm mode 199The current file's permissions as a numeric (octal) or symbolic 200value. 201.It Cm nlink 202The number of hard links the file is expected to have. 203.It Cm nochange 204Make sure this file or directory exists but otherwise ignore all attributes. 205.It Cm optional 206The file is optional; do not complain about the file if it is not in 207the file hierarchy. 208.It Cm resdevice 209The 210.Dq resident 211device number of the file, e.g. the ID of the device that 212contains the file. 213Its format is the same as the one for 214.Cm device . 215.It Cm ripemd160digest 216The 217.Tn RIPEMD160 218message digest of the file. 219.It Cm rmd160 220A synonym for 221.Cm ripemd160digest . 222.It Cm rmd160digest 223A synonym for 224.Cm ripemd160digest . 225.It Cm sha1 226The 227.Tn FIPS 228160-1 229.Pq Dq Tn SHA-1 230message digest of the file. 231.It Cm sha1digest 232A synonym for 233.Cm sha1 . 234.It Cm sha256 235The 236.Tn FIPS 237180-2 238.Pq Dq Tn SHA-256 239message digest of the file. 240.It Cm sha256digest 241A synonym for 242.Cm sha256 . 243.It Cm sha384 244The 245.Tn FIPS 246180-2 247.Pq Dq Tn SHA-384 248message digest of the file. 249.It Cm sha384digest 250A synonym for 251.Cm sha384 . 252.It Cm sha512 253The 254.Tn FIPS 255180-2 256.Pq Dq Tn SHA-512 257message digest of the file. 258.It Cm sha512digest 259A synonym for 260.Cm sha512 . 261.It Cm size 262The size, in bytes, of the file. 263.It Cm time 264The last modification time of the file. 265.It Cm type 266The type of the file; may be set to any one of the following: 267.Pp 268.Bl -tag -width Cm -compact 269.It Cm block 270block special device 271.It Cm char 272character special device 273.It Cm dir 274directory 275.It Cm fifo 276fifo 277.It Cm file 278regular file 279.It Cm link 280symbolic link 281.It Cm socket 282socket 283.El 284.It Cm uid 285The file owner as a numeric value. 286.It Cm uname 287The file owner as a symbolic name. 288.El 289.Sh SEE ALSO 290.Xr cksum 1 , 291.Xr find 1 , 292.Xr mtree 8 293.Sh HISTORY 294The 295.Nm 296utility appeared in 297.Bx 4.3 Reno . 298The 299.Tn MD5 300digest capability was added in 301.Fx 2.1 , 302in response to the widespread use of programs which can spoof 303.Xr cksum 1 . 304The 305.Tn SHA-1 306and 307.Tn RIPEMD160 308digests were added in 309.Fx 4.0 , 310as new attacks have demonstrated weaknesses in 311.Tn MD5 . 312The 313.Tn SHA-256 314digest was added in 315.Fx 6.0 . 316Support for file flags was added in 317.Fx 4.0 , 318and mostly comes from 319.Nx . 320The 321.Dq full 322entry format was added by 323.Nx . 324