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