xref: /original-bsd/usr.sbin/mtree/mtree.8 (revision d54be081)
1.\" Copyright (c) 1989, 1990 The Regents of the University of California.
2.\" All rights reserved.
3.\"
4.\" %sccs.include.redist.roff%
5.\"
6.\"     @(#)mtree.8	5.9 (Berkeley) 05/31/91
7.\"
8.Dd
9.Dt MTREE 8
10.Os
11.Sh NAME
12.Nm mtree
13.Nd map a directory hierarchy
14.Sh SYNOPSIS
15.Nm mtree
16.Op Fl cderux
17.Op Fl f Ar spec
18.Op Fl p Ar path
19.Sh DESCRIPTION
20The utility
21.Nm mtree
22compares a directory hierarchy against a specification for a
23directory hierarchy.
24By default, the specification is read from the standard input.
25.Nm Mtree
26verifies that the tree rooted in the current directory matches the
27specification.
28.Pp
29Messages are written to standard output for any files whose
30characteristics do not match those of the specification, or which are
31missing from either the specification or the tree.
32.Pp
33The options are as follows:
34.Bl -tag -width Fl c
35.It Fl c
36Print a specification for the tree to standard output.
37.It Fl d
38Ignore everything except directory type files.
39.It Fl e
40Don't object to files that are in the tree but not in the specification.
41.It Fl f
42Read the specification from
43.Ar file  ,
44instead of from standard input.
45.It Fl p
46Traverse the tree rooted in
47.Ar path  ,
48instead of the current directory.
49.It Fl r
50Remove any files in the tree that are not described in the
51specification.
52.It Fl u
53Modify the owner, group, and permissions of existing files to match
54the specification, as well as create any missing directories.
55Owner, group, and permissions must all be specified for missing
56directories to be created.
57.It Fl x
58Don't descend below any mount points.
59.El
60.Pp
61Specifications are mostly composed of ``keywords'', i.e. strings that
62that specify values relating to files.
63No keywords have default values, and if a keyword has no set value no
64checks based on it are performed.
65.Pp
66Currently supported keywords are as follows:
67.Bl -tag -width Cm
68.It Cm cksum
69The checksum of the file using the algorithm specified by
70the program
71.Xr cksum  1  .
72.It Cm ignore
73Causes the hierarchy below the file to be ignored.
74.It Cm group
75The group of the file; may be either numeric or symbolic.
76.It Cm mode
77The current file's permissions as an absolute (octal) or symbolic
78value (see
79.Xr chmod  1  ) .
80.It Cm nlink
81The number of hard links the file is expected to have.
82.It Cm owner
83The owner of the file; may be either numeric or symbolic.
84.It Cm size
85The size, in bytes, of the file.
86.It Cm link
87The file a symbolic link is expected to reference.
88.It Cm time
89The last modification time of the file.
90.It Cm type
91The type of the file; may be set to any one of the following:
92.Bl -tag -width Cm
93.It Cm block
94block special device
95.It Cm char
96character special device
97.It Cm dir
98directory
99.It Cm fifo
100fifo
101.It Cm file
102regular file
103.It Cm link
104symbolic link
105.It Cm socket
106socket
107.El
108.El
109.Pp
110There are four types of lines in a specification.
111.Pp
112The first type of line sets a ``global'' value for a keyword, and
113consists of a leading ``/set'' followed by whitespace, followed by
114sets of keyword/value pairs, separated by whitespace.
115Keyword/value pairs consist of a keyword, followed by a equals sign
116(``=''), followed by a value, without intervening whitespace.
117Once a keyword has been set, its value remains unchanged until either
118set again or unset.
119.Pp
120The second type of line unsets keywords and consists of a leading
121``/unset'', followed by whitespace, followed by one or more keywords,
122separated by whitespace.
123.Pp
124The third type of line is a file specification and consists of a file
125name, followed by whitespace, followed by zero or more whitespace
126separated keyword/value pairs.
127The file name may be preceded by any number of whitespace characters.
128The file name may contain any of the standard file name matching
129characters (``['', ``]'', ``?'' or ``*''), in which case files
130in the hierarchy will be associated with the first pattern that
131they match.
132.Pp
133Each of the keyword/value pairs consist of a keyword, followed by an
134equals sign (``=''), followed by the keyword's value, without intervening
135whitespace.
136These values override, without changing, the global value of the
137corresponding keyword.
138.Pp
139All paths are relative.
140Specifying a directory will cause subsequent files to be searched
141for in that directory hierarchy.
142Which brings us to the last type of line in a specification: a line
143containing only the string
144.Dq Nm \&..
145causes the current directory
146path to ascend one level.
147.Pp
148Empty lines and lines whose first non-whitespace character is a hash
149mark (``#'') are ignored.
150.Pp
151.Nm Mtree
152exits with a status of 0 on success and >0 if an error occurred or the
153tree did not match the specification.
154.Sh FILES
155.Bl -tag -width /etc/mtree -compact
156.It Pa /etc/mtree
157system specification directory
158.El
159.Sh SEE ALSO
160.Xr chmod 1 ,
161.Xr chown 1 ,
162.Xr chgrp 1 ,
163.Xr cksum 1 ,
164.Xr find 1 ,
165.Xr stat 2 ,
166.Xr fts 3 ,
167.Xr mkproto 8
168.Sh BUGS
169The
170.Cm cksum
171keyword is not yet implemented.
172.Pp
173The
174.Cm time
175keyword should be specifiable in human readable terms.
176.Sh EXAMPLE
177.Bd -literal -offset indent -compact
178#	  fs: /a/staff/rick/mybin
179#	  by: rick
180#	date: Fri May 25 12:26:57 1990
181
182/set group=staff mode=0555 nlink=1 owner=rick type=file
183[ 		nlink=2 size=6144
184adb		size=53248
185df		group=operator mode=02555 size=20480
186ps		group=kmem mode=02555 size=54272
187rcp		owner=root mode=04555 size=79872
188test		nlink=2 size=6144
189
190/set group=wheel mode=0444 nlink=1 owner=rick type=file
191manpages	type=dir mode=0775 nlink=2 size=1024
192adb.man	size=9473
193df.man	size=5263
194tar.man	size=3324
195\&..
196.Ed
197.Sh HISTORY
198The
199.Nm mtree
200utility appeared in
201.Bx 4.3 Reno .
202