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 August 20, 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 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 definition 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 that holds the contents of this file.
 139 .It Cm flags
 140 The file flags as a symbolic name.
 141 See
 142 .Xr chflags 1
 143 for information on these names.
 144 If no flags are to be set the string
 145 .Dq none
 146 may be used to override the current default.
 147 .It Cm gid
 148 The file group as a numeric value.
 149 .It Cm gname
 150 The file group as a symbolic name.
 151 .It Cm ignore
 152 Ignore any file hierarchy below this file.
 153 .It Cm link
 154 The target of the symbolic link when type=link.
 155 .It Cm md5
 156 The MD5 message digest of the file.
 157 .It Cm md5digest
 158 A synonym for
 159 .Cm md5 .
 160 .It Cm mode
 161 The current file's permissions as a numeric (octal) or symbolic
 162 value.
 163 .It Cm nlink
 164 The number of hard links the file is expected to have.
 165 .It Cm nochange
 166 Make sure this file or directory exists but otherwise ignore all attributes.
 167 .It Cm ripemd160digest
 168 The
 169 .Tn RIPEMD160
 170 message digest of the file.
 171 .It Cm rmd160
 172 A synonym for
 173 .Cm ripemd160digest .
 174 .It Cm rmd160digest
 175 A synonym for
 176 .Cm ripemd160digest .
 177 .It Cm sha1
 178 The
 179 .Tn FIPS
 180 160-1
 181 .Pq Dq Tn SHA-1
 182 message digest of the file.
 183 .It Cm sha1digest
 184 A synonym for
 185 .Cm sha1 .
 186 .It Cm sha256
 187 The
 188 .Tn FIPS
 189 180-2
 190 .Pq Dq Tn SHA-256
 191 message digest of the file.
 192 .It Cm sha256digest
 193 A synonym for
 194 .Cm sha256 .
 195 .It Cm size
 196 The size, in bytes, of the file.
 197 .It Cm time
 198 The last modification time of the file.
 199 .It Cm type
 200 The type of the file; may be set to any one of the following:
 201 .Pp
 202 .Bl -tag -width Cm -compact
 203 .It Cm block
 204 block special device
 205 .It Cm char
 206 character special device
 207 .It Cm dir
 208 directory
 209 .It Cm fifo
 210 fifo
 211 .It Cm file
 212 regular file
 213 .It Cm link
 214 symbolic link
 215 .It Cm socket
 216 socket
 217 .El
 218 .It Cm uid
 219 The file owner as a numeric value.
 220 .It Cm uname
 221 The file owner as a symbolic name.
 222 .El
 223 .Pp
 224 .Sh SEE ALSO
 225 .Xr cksum 1 ,
 226 .Xr find 1 ,
 227 .Xr mtree 8
 228 .Sh BUGS
 229 The
 230 .Fx
 231 implementation of mtree does not currently support
 232 the
 233 .Nm
 234 2.0
 235 format.
 236 The requirement for a
 237 .Dq #mtree
 238 signature line is new and not yet widely implemented.
 239 .Sh HISTORY
 240 The
 241 .Nm
 242 utility appeared in
 243 .Bx 4.3 Reno .
 244 The
 245 .Tn MD5
 246 digest capability was added in
 247 .Fx 2.1 ,
 248 in response to the widespread use of programs which can spoof
 249 .Xr cksum 1 .
 250 The
 251 .Tn SHA-1
 252 and
 253 .Tn RIPEMD160
 254 digests were added in
 255 .Fx 4.0 ,
 256 as new attacks have demonstrated weaknesses in
 257 .Tn MD5 .
 258 The
 259 .Tn SHA-256
 260 digest was added in
 261 .Fx 6.0 .
 262 Support for file flags was added in
 263 .Fx 4.0 ,
 264 and mostly comes from
 265 .Nx .
 266 The
 267 .Dq full
 268 entry format was added by
 269 .Nx .