usr.sbin/mtree/mtree.5

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