doc/wiki/ManPageMtree5.wiki

   1 MTREE(5) manual page
   2 == NAME ==
   3 '''mtree'''
   4 - format of mtree dir hierarchy files
   5 == DESCRIPTION ==
   6 The
   7 '''mtree'''
   8 format is a textual format that describes a collection of filesystem objects.
   9 Such files are typically used to create or verify directory hierarchies.
  10 === General Format===
  11 An
  12 '''mtree'''
  13 file consists of a series of lines, each providing information
  14 about a single filesystem object.
  15 Leading whitespace is always ignored.
  16
  17 When encoding file or pathnames, any backslash character or
  18 character outside of the 95 printable ASCII characters must be
  19 encoded as a backslash followed by three
  20 octal digits.
  21 When reading mtree files, any appearance of a backslash
  22 followed by three octal digits should be converted into the
  23 corresponding character.
  24
  25 Each line is interpreted independently as one of the following types:
  26 <dl>
  27 <dt>Blank</dt><dd>
  28 Blank lines are ignored.
  29 </dd><dt>Comment</dt><dd>
  30 Lines beginning with
  31 '''#'''
  32 are ignored.
  33 </dd><dt>Special</dt><dd>
  34 Lines beginning with
  35 '''/'''
  36 are special commands that influence
  37 the interpretation of later lines.
  38 </dd><dt>Relative</dt><dd>
  39 If the first whitespace-delimited word has no
  40 '''/'''
  41 characters,
  42 it is the name of a file in the current directory.
  43 Any relative entry that describes a directory changes the
  44 current directory.
  45 </dd><dt>dot-dot</dt><dd>
  46 As a special case, a relative entry with the filename
  47 ''..''
  48 changes the current directory to the parent directory.
  49 Options on dot-dot entries are always ignored.
  50 </dd><dt>Full</dt><dd>
  51 If the first whitespace-delimited word has a
  52 '''/'''
  53 character after
  54 the first character, it is the pathname of a file relative to the
  55 starting directory.
  56 There can be multiple full entries describing the same file.
  57 </dd></dl>
  58
  59 Some tools that process
  60 '''mtree'''
  61 files may require that multiple lines describing the same file
  62 occur consecutively.
  63 It is not permitted for the same file to be mentioned using
  64 both a relative and a full file specification.
  65 === Special commands===
  66 Two special commands are currently defined:
  67 <dl>
  68 <dt>'''/set'''</dt><dd>
  69 This command defines default values for one or more keywords.
  70 It is followed on the same line by one or more whitespace-separated
  71 keyword definitions.
  72 These definitions apply to all following files that do not specify
  73 a value for that keyword.
  74 </dd><dt>'''/unset'''</dt><dd>
  75 This command removes any default value set by a previous
  76 '''/set'''
  77 command.
  78 It is followed on the same line by one or more keywords
  79 separated by whitespace.
  80 </dd></dl>
  81 === Keywords===
  82 After the filename, a full or relative entry consists of zero
  83 or more whitespace-separated keyword definitions.
  84 Each such definition consists of a key from the following
  85 list immediately followed by an '=' sign
  86 and a value.
  87 Software programs reading mtree files should warn about
  88 unrecognized keywords.
  89
  90 Currently supported keywords are as follows:
  91 <dl>
  92 <dt>'''cksum'''</dt><dd>
  93 The checksum of the file using the default algorithm specified by
  94 the
  95 [[cksum(1)|http://www.freebsd.org/cgi/man.cgi?query=cksum&sektion=1]]
  96 utility.
  97 </dd><dt>'''device'''</dt><dd>
  98 The device number for
  99 .B block
 100 or
 101 .B char
 102 file types.
 103 The value must be one of the following forms:
 104
 105 <dl>
 106 <dt>''format'',''major'',''minor''Bo,''subunit'' Bc</dt><dd>
 107 A device with
 108 ''major'', minor
 109 and optional
 110 ''subunit''
 111 fields.
 112 Their meaning is specified by the operating's system
 113 ''format''.
 114 See below for valid formats.
 115 </dd><dt>''number''</dt><dd>
 116 Opaque number (as stored on the file system).
 117 </dd></dl>
 118
 119 The following values for
 120 ''format''
 121 are recognized:
 122 .B native ,
 123 .B 386bsd ,
 124 .B 4bsd ,
 125 .B bsdos ,
 126 .B freebsd ,
 127 .B hpux ,
 128 .B isc ,
 129 .B linux ,
 130 .B netbsd ,
 131 .B osf1 ,
 132 .B sco ,
 133 .B solaris ,
 134 .B sunos ,
 135 .B svr3 ,
 136 .B svr4 ,
 137 and
 138 .B ultrix .
 139
 140 See
 141 [[mknod(8)|http://www.freebsd.org/cgi/man.cgi?query=mknod&sektion=8]]
 142 for more details.
 143 </dd><dt>'''contents'''</dt><dd>
 144 The full pathname of a file that holds the contents of this file.
 145 </dd><dt>'''flags'''</dt><dd>
 146 The file flags as a symbolic name.
 147 See
 148 [[chflags(1)|http://www.freebsd.org/cgi/man.cgi?query=chflags&sektion=1]]
 149 for information on these names.
 150 If no flags are to be set the string
 151 "none"
 152 may be used to override the current default.
 153 </dd><dt>'''gid'''</dt><dd>
 154 The file group as a numeric value.
 155 </dd><dt>'''gname'''</dt><dd>
 156 The file group as a symbolic name.
 157 </dd><dt>'''ignore'''</dt><dd>
 158 Ignore any file hierarchy below this file.
 159 </dd><dt>'''inode'''</dt><dd>
 160 The inode number.
 161 </dd><dt>'''link'''</dt><dd>
 162 The target of the symbolic link when type=link.
 163 </dd><dt>'''md5'''</dt><dd>
 164 The MD5 message digest of the file.
 165 </dd><dt>'''md5digest'''</dt><dd>
 166 A synonym for
 167 '''md5'''.
 168 </dd><dt>'''mode'''</dt><dd>
 169 The current file's permissions as a numeric (octal) or symbolic
 170 value.
 171 </dd><dt>'''nlink'''</dt><dd>
 172 The number of hard links the file is expected to have.
 173 </dd><dt>'''nochange'''</dt><dd>
 174 Make sure this file or directory exists but otherwise ignore all attributes.
 175 </dd><dt>'''optional'''</dt><dd>
 176 The file is optional; do not complain about the file if it is not in
 177 the file hierarchy.
 178 </dd><dt>'''resdevice'''</dt><dd>
 179 The
 180 "resident"
 181 device number of the file, e.g. the ID of the device that
 182 contains the file.
 183 Its format is the same as the one for
 184 '''device'''.
 185 </dd><dt>'''ripemd160digest'''</dt><dd>
 186 The
 187 '''RIPEMD160'''
 188 message digest of the file.
 189 </dd><dt>'''rmd160'''</dt><dd>
 190 A synonym for
 191 '''ripemd160digest'''.
 192 </dd><dt>'''rmd160digest'''</dt><dd>
 193 A synonym for
 194 '''ripemd160digest'''.
 195 </dd><dt>'''sha1'''</dt><dd>
 196 The
 197 '''FIPS'''
 198 160-1
 199 ("Tn SHA-1")
 200 message digest of the file.
 201 </dd><dt>'''sha1digest'''</dt><dd>
 202 A synonym for
 203 '''sha1'''.
 204 </dd><dt>'''sha256'''</dt><dd>
 205 The
 206 '''FIPS'''
 207 180-2
 208 ("Tn SHA-256")
 209 message digest of the file.
 210 </dd><dt>'''sha256digest'''</dt><dd>
 211 A synonym for
 212 '''sha256'''.
 213 </dd><dt>'''sha384'''</dt><dd>
 214 The
 215 '''FIPS'''
 216 180-2
 217 ("Tn SHA-384")
 218 message digest of the file.
 219 </dd><dt>'''sha384digest'''</dt><dd>
 220 A synonym for
 221 '''sha384'''.
 222 </dd><dt>'''sha512'''</dt><dd>
 223 The
 224 '''FIPS'''
 225 180-2
 226 ("Tn SHA-512")
 227 message digest of the file.
 228 </dd><dt>'''sha512digest'''</dt><dd>
 229 A synonym for
 230 '''sha512'''.
 231 </dd><dt>'''size'''</dt><dd>
 232 The size, in bytes, of the file.
 233 </dd><dt>'''time'''</dt><dd>
 234 The last modification time of the file.
 235 </dd><dt>'''type'''</dt><dd>
 236 The type of the file; may be set to any one of the following:
 237
 238 <dl>
 239 <dt>'''block'''</dt><dd>
 240 block special device
 241 </dd><dt>'''char'''</dt><dd>
 242 character special device
 243 </dd><dt>'''dir'''</dt><dd>
 244 directory
 245 </dd><dt>'''fifo'''</dt><dd>
 246 fifo
 247 </dd><dt>'''file'''</dt><dd>
 248 regular file
 249 </dd><dt>'''link'''</dt><dd>
 250 symbolic link
 251 </dd><dt>'''socket'''</dt><dd>
 252 socket
 253 </dd></dl>
 254 </dd><dt>'''uid'''</dt><dd>
 255 The file owner as a numeric value.
 256 </dd><dt>'''uname'''</dt><dd>
 257 The file owner as a symbolic name.
 258 </dd></dl>
 259
 260 == SEE ALSO ==
 261 [[cksum(1)|http://www.freebsd.org/cgi/man.cgi?query=cksum&sektion=1]],
 262 [[find(1)|http://www.freebsd.org/cgi/man.cgi?query=find&sektion=1]],
 263 [[mtree(8)|http://www.freebsd.org/cgi/man.cgi?query=mtree&sektion=8]]
 264 == BUGS ==
 265 == HISTORY ==
 266 The
 267 '''mtree'''
 268 utility appeared in
 269 BSD 4.3 Reno.
 270 The
 271 '''MD5'''
 272 digest capability was added in
 273 FreeBSD 2.1,
 274 in response to the widespread use of programs which can spoof
 275 [[cksum(1)|http://www.freebsd.org/cgi/man.cgi?query=cksum&sektion=1]].
 276 The
 277 '''SHA-1'''
 278 and
 279 '''RIPEMD160'''
 280 digests were added in
 281 FreeBSD 4.0,
 282 as new attacks have demonstrated weaknesses in
 283 '''MD5 .'''
 284 The
 285 '''SHA-256'''
 286 digest was added in
 287 FreeBSD 6.0.
 288 Support for file flags was added in
 289 FreeBSD 4.0,
 290 and mostly comes from
 291 NetBSD.
 292 The
 293 "full"
 294 entry format was added by
 295 NetBSD.