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