MFC r1.27:
[dragonfly.git] / contrib / libarchive-2 / libarchive / mtree.5
blobb6637d6f55e8b8ff39909013b12560187a82c070
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
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
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.
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.
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
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.
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
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
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
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:
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
218 .It Cm uid
219 The file owner as a numeric value.
220 .It Cm uname
221 The file owner as a symbolic name.
224 .Sh SEE ALSO
225 .Xr cksum 1 ,
226 .Xr find 1 ,
227 .Xr mtree 8
228 .Sh BUGS
231 implementation of mtree does not currently support
235 format.
236 The requirement for a
237 .Dq #mtree
238 signature line is new and not yet widely implemented.
239 .Sh HISTORY
242 utility appeared in
243 .Bx 4.3 Reno .
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 .
251 .Tn SHA-1
253 .Tn RIPEMD160
254 digests were added in
255 .Fx 4.0 ,
256 as new attacks have demonstrated weaknesses in
257 .Tn MD5 .
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 .
267 .Dq full
268 entry format was added by
269 .Nx .