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