contrib/libarchive/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 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 .Bl -tag -width 4n
 137 .It Ar format , Ns Ar major , Ns Ar minor Ns Bo , Ns Ar subunit Bc
 138 A device with
 139 .Ar major , minor
 140 and optional
 141 .Ar subunit
 142 fields.
 143 Their meaning is specified by the operating's system
 144 .Ar format .
 145 See below for valid formats.
 146 .It Ar number
 147 Opaque number (as stored on the file system).
 148 .El
 149 .Pp
 150 The following values for
 151 .Ar format
 152 are recognized:
 153 .Sy native ,
 154 .Sy 386bsd ,
 155 .Sy 4bsd ,
 156 .Sy bsdos ,
 157 .Sy freebsd ,
 158 .Sy hpux ,
 159 .Sy isc ,
 160 .Sy linux ,
 161 .Sy netbsd ,
 162 .Sy osf1 ,
 163 .Sy sco ,
 164 .Sy solaris ,
 165 .Sy sunos ,
 166 .Sy svr3 ,
 167 .Sy svr4 ,
 168 and
 169 .Sy ultrix .
 170 .Pp
 171 See
 172 .Xr mknod 8
 173 for more details.
 174 .It Cm contents
 175 The full pathname of a file that holds the contents of this file.
 176 .It Cm flags
 177 The file flags as a symbolic name.
 178 See
 179 .Xr chflags 1
 180 for information on these names.
 181 If no flags are to be set the string
 182 .Dq none
 183 may be used to override the current default.
 184 .It Cm gid
 185 The file group as a numeric value.
 186 .It Cm gname
 187 The file group as a symbolic name.
 188 .It Cm ignore
 189 Ignore any file hierarchy below this file.
 190 .It Cm inode
 191 The inode number.
 192 .It Cm link
 193 The target of the symbolic link when type=link.
 194 .It Cm md5
 195 The MD5 message digest of the file.
 196 .It Cm md5digest
 197 A synonym for
 198 .Cm md5 .
 199 .It Cm mode
 200 The current file's permissions as a numeric (octal) or symbolic
 201 value.
 202 .It Cm nlink
 203 The number of hard links the file is expected to have.
 204 .It Cm nochange
 205 Make sure this file or directory exists but otherwise ignore all attributes.
 206 .It Cm optional
 207 The file is optional; do not complain about the file if it is not in
 208 the file hierarchy.
 209 .It Cm resdevice
 210 The
 211 .Dq resident
 212 device number of the file, e.g. the ID of the device that
 213 contains the file.
 214 Its format is the same as the one for
 215 .Cm device .
 216 .It Cm ripemd160digest
 217 The
 218 .Tn RIPEMD160
 219 message digest of the file.
 220 .It Cm rmd160
 221 A synonym for
 222 .Cm ripemd160digest .
 223 .It Cm rmd160digest
 224 A synonym for
 225 .Cm ripemd160digest .
 226 .It Cm sha1
 227 The
 228 .Tn FIPS
 229 160-1
 230 .Pq Dq Tn SHA-1
 231 message digest of the file.
 232 .It Cm sha1digest
 233 A synonym for
 234 .Cm sha1 .
 235 .It Cm sha256
 236 The
 237 .Tn FIPS
 238 180-2
 239 .Pq Dq Tn SHA-256
 240 message digest of the file.
 241 .It Cm sha256digest
 242 A synonym for
 243 .Cm sha256 .
 244 .It Cm sha384
 245 The
 246 .Tn FIPS
 247 180-2
 248 .Pq Dq Tn SHA-384
 249 message digest of the file.
 250 .It Cm sha384digest
 251 A synonym for
 252 .Cm sha384 .
 253 .It Cm sha512
 254 The
 255 .Tn FIPS
 256 180-2
 257 .Pq Dq Tn SHA-512
 258 message digest of the file.
 259 .It Cm sha512digest
 260 A synonym for
 261 .Cm sha512 .
 262 .It Cm size
 263 The size, in bytes, of the file.
 264 .It Cm time
 265 The last modification time of the file.
 266 .It Cm type
 267 The type of the file; may be set to any one of the following:
 268 .Pp
 269 .Bl -tag -width Cm -compact
 270 .It Cm block
 271 block special device
 272 .It Cm char
 273 character special device
 274 .It Cm dir
 275 directory
 276 .It Cm fifo
 277 fifo
 278 .It Cm file
 279 regular file
 280 .It Cm link
 281 symbolic link
 282 .It Cm socket
 283 socket
 284 .El
 285 .It Cm uid
 286 The file owner as a numeric value.
 287 .It Cm uname
 288 The file owner as a symbolic name.
 289 .El
 290 .Sh SEE ALSO
 291 .Xr cksum 1 ,
 292 .Xr find 1 ,
 293 .Xr mtree 8
 294 .Sh HISTORY
 295 The
 296 .Nm
 297 utility appeared in
 298 .Bx 4.3 Reno .
 299 The
 300 .Tn MD5
 301 digest capability was added in
 302 .Fx 2.1 ,
 303 in response to the widespread use of programs which can spoof
 304 .Xr cksum 1 .
 305 The
 306 .Tn SHA-1
 307 and
 308 .Tn RIPEMD160
 309 digests were added in
 310 .Fx 4.0 ,
 311 as new attacks have demonstrated weaknesses in
 312 .Tn MD5 .
 313 The
 314 .Tn SHA-256
 315 digest was added in
 316 .Fx 6.0 .
 317 Support for file flags was added in
 318 .Fx 4.0 ,
 319 and mostly comes from
 320 .Nx .
 321 The
 322 .Dq full
 323 entry format was added by
 324 .Nx .