xref: /illumos-gate/usr/src/cmd/filesync/README (revision 7c478bd95313f5f23a4c958a745db2134aa03244)
1 *7c478bd9Sstevel@tonic-gate#
2 *7c478bd9Sstevel@tonic-gate# CDDL HEADER START
3 *7c478bd9Sstevel@tonic-gate#
4 *7c478bd9Sstevel@tonic-gate# The contents of this file are subject to the terms of the
5 *7c478bd9Sstevel@tonic-gate# Common Development and Distribution License, Version 1.0 only
6 *7c478bd9Sstevel@tonic-gate# (the "License").  You may not use this file except in compliance
7 *7c478bd9Sstevel@tonic-gate# with the License.
8 *7c478bd9Sstevel@tonic-gate#
9 *7c478bd9Sstevel@tonic-gate# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10 *7c478bd9Sstevel@tonic-gate# or http://www.opensolaris.org/os/licensing.
11 *7c478bd9Sstevel@tonic-gate# See the License for the specific language governing permissions
12 *7c478bd9Sstevel@tonic-gate# and limitations under the License.
13 *7c478bd9Sstevel@tonic-gate#
14 *7c478bd9Sstevel@tonic-gate# When distributing Covered Code, include this CDDL HEADER in each
15 *7c478bd9Sstevel@tonic-gate# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16 *7c478bd9Sstevel@tonic-gate# If applicable, add the following below this CDDL HEADER, with the
17 *7c478bd9Sstevel@tonic-gate# fields enclosed by brackets "[]" replaced with your own identifying
18 *7c478bd9Sstevel@tonic-gate# information: Portions Copyright [yyyy] [name of copyright owner]
19 *7c478bd9Sstevel@tonic-gate#
20 *7c478bd9Sstevel@tonic-gate# CDDL HEADER END
21 *7c478bd9Sstevel@tonic-gate#
22 *7c478bd9Sstevel@tonic-gate# Copyright (c) 1995 Sun Microsystems, Inc.  All Rights Reserved
23 *7c478bd9Sstevel@tonic-gate#
24 *7c478bd9Sstevel@tonic-gate#ident	"%W%	%E% SMI"
25 *7c478bd9Sstevel@tonic-gate#
26 *7c478bd9Sstevel@tonic-gate#	design notes that are likely to be of general (rather than
27 *7c478bd9Sstevel@tonic-gate#	merely historical) interest.
28 *7c478bd9Sstevel@tonic-gate
29 *7c478bd9Sstevel@tonic-gateTable of Contents
30 *7c478bd9Sstevel@tonic-gate
31 *7c478bd9Sstevel@tonic-gate	Overview			what filesync does
32 *7c478bd9Sstevel@tonic-gate
33 *7c478bd9Sstevel@tonic-gate	Primary Data Structures
34 *7c478bd9Sstevel@tonic-gate		general principles	why they exist
35 *7c478bd9Sstevel@tonic-gate		key concepts		what they represent
36 *7c478bd9Sstevel@tonic-gate		data structures		major structures and their contents
37 *7c478bd9Sstevel@tonic-gate
38 *7c478bd9Sstevel@tonic-gate	Overview of Passes		main phases of program execution
39 *7c478bd9Sstevel@tonic-gate
40 *7c478bd9Sstevel@tonic-gate	Modules				list and descriptions of files
41 *7c478bd9Sstevel@tonic-gate
42 *7c478bd9Sstevel@tonic-gate	Studying the Code
43 *7c478bd9Sstevel@tonic-gate		active ingredients	a reading list of high points
44 *7c478bd9Sstevel@tonic-gate		the whole thing		a suggested order for everything
45 *7c478bd9Sstevel@tonic-gate
46 *7c478bd9Sstevel@tonic-gate	Gross calling structure		who calls whom
47 *7c478bd9Sstevel@tonic-gate
48 *7c478bd9Sstevel@tonic-gate	Helpful hints			good things to know
49 *7c478bd9Sstevel@tonic-gate
50 *7c478bd9Sstevel@tonic-gateOverview
51 *7c478bd9Sstevel@tonic-gate
52 *7c478bd9Sstevel@tonic-gate	The purpose of this program is to compare pairs of directory
53 *7c478bd9Sstevel@tonic-gate	trees with a baseline snapshot, to determine which files have
54 *7c478bd9Sstevel@tonic-gate	changed, and to propagate the changes in order to bring the
55 *7c478bd9Sstevel@tonic-gate	trees back into congruency.  The baseline snapshot describes
56 *7c478bd9Sstevel@tonic-gate	size, ownership, ... for all files that filesync is managing
57 *7c478bd9Sstevel@tonic-gate	WHEN THEY WERE LAST IN SYNC.
58 *7c478bd9Sstevel@tonic-gate
59 *7c478bd9Sstevel@tonic-gate	The files and directory trees to be compared are determined
60 *7c478bd9Sstevel@tonic-gate	by a relatively flexible (user editable) rules file, whose
61 *7c478bd9Sstevel@tonic-gate	format (packingrules.4) permits files and or trees to be
62 *7c478bd9Sstevel@tonic-gate	specified, explicitly, implicitly, or with wild cards.
63 *7c478bd9Sstevel@tonic-gate	There are also provisions for filtering out unwanted files
64 *7c478bd9Sstevel@tonic-gate	and for running programs to generate lists of files and
65 *7c478bd9Sstevel@tonic-gate	directories to be included or excluded.
66 *7c478bd9Sstevel@tonic-gate
67 *7c478bd9Sstevel@tonic-gate	The comparisons begin by comparing the structured name
68 *7c478bd9Sstevel@tonic-gate	spaces.  For names that appear in both trees, the files
69 *7c478bd9Sstevel@tonic-gate	are then compared on the basis of type, size, contents,
70 *7c478bd9Sstevel@tonic-gate	ownership and protections.  For files that are already
71 *7c478bd9Sstevel@tonic-gate	in the baseline snapshot, if the sizes and modification
72 *7c478bd9Sstevel@tonic-gate	times have not changed, we do not bother to recheck the
73 *7c478bd9Sstevel@tonic-gate	contents.
74 *7c478bd9Sstevel@tonic-gate
75 *7c478bd9Sstevel@tonic-gate	The reconciliation process (resolving the differences)
76 *7c478bd9Sstevel@tonic-gate	will only propagate a change if it is obvious what should
77 *7c478bd9Sstevel@tonic-gate	be done (one side has changed relative to the snapshot,
78 *7c478bd9Sstevel@tonic-gate	while the other has not).  If there are conflicting changes,
79 *7c478bd9Sstevel@tonic-gate	the file is flagged and the user is asked to reconcile the
80 *7c478bd9Sstevel@tonic-gate	differences manually.  There are, however a few switches
81 *7c478bd9Sstevel@tonic-gate	that can be used to constrain the analysis or reconciliation,
82 *7c478bd9Sstevel@tonic-gate	or to force one particular side to win in case of a conflict.
83 *7c478bd9Sstevel@tonic-gate
84 *7c478bd9Sstevel@tonic-gate
85 *7c478bd9Sstevel@tonic-gatePrimary Data Structures
86 *7c478bd9Sstevel@tonic-gate
87 *7c478bd9Sstevel@tonic-gate	general principles:
88 *7c478bd9Sstevel@tonic-gate		we will build up an in-memory tree that represents
89 *7c478bd9Sstevel@tonic-gate		the union of the name spaces found in the baseline
90 *7c478bd9Sstevel@tonic-gate		and on the source and destination sides.
91 *7c478bd9Sstevel@tonic-gate
92 *7c478bd9Sstevel@tonic-gate		keep in mind that the baseline recalls the state of
93 *7c478bd9Sstevel@tonic-gate		files THE LAST TIME THEY WERE IN AGREEMENT.  If files
94 *7c478bd9Sstevel@tonic-gate		have disagreed for a long time, the baseline still
95 *7c478bd9Sstevel@tonic-gate		remembers what they were like when they agreed.  If
96 *7c478bd9Sstevel@tonic-gate		files have never agreed, the baseline has no notions
97 *7c478bd9Sstevel@tonic-gate		of how they "used to be".
98 *7c478bd9Sstevel@tonic-gate
99 *7c478bd9Sstevel@tonic-gate	key concepts:
100 *7c478bd9Sstevel@tonic-gate		a "base pair" is a pair of directories whose
101 *7c478bd9Sstevel@tonic-gate		contents (or a subset of whose contents) are to
102 *7c478bd9Sstevel@tonic-gate		be syncrhonized.  The "base pairs" to be managed
103 *7c478bd9Sstevel@tonic-gate		are specified in the packing rules file.
104 *7c478bd9Sstevel@tonic-gate
105 *7c478bd9Sstevel@tonic-gate		associated with each "base pair" is a set of rules
106 *7c478bd9Sstevel@tonic-gate		that describe which files (under those directories)
107 *7c478bd9Sstevel@tonic-gate		are to be kept in sync.  Each rule is a list of:
108 *7c478bd9Sstevel@tonic-gate			files and or directories to be included
109 *7c478bd9Sstevel@tonic-gate			wild cards for files or directories to be included
110 *7c478bd9Sstevel@tonic-gate			programs to generate lists of names for inclusion
111 *7c478bd9Sstevel@tonic-gate			file names to be ignored
112 *7c478bd9Sstevel@tonic-gate			wild cards for file names to be ignored
113 *7c478bd9Sstevel@tonic-gate			programs to generate lists of names for ignoring
114 *7c478bd9Sstevel@tonic-gate
115 *7c478bd9Sstevel@tonic-gate		as a result of the "evaluation" process we build up
116 *7c478bd9Sstevel@tonic-gate		(under each base pair) a tree that represents all of
117 *7c478bd9Sstevel@tonic-gate		the files that we are supposed to keep in sync, and
118 *7c478bd9Sstevel@tonic-gate		contains everything we need to know about each one
119 *7c478bd9Sstevel@tonic-gate		of those files.  The structure of the tree mirrors
120 *7c478bd9Sstevel@tonic-gate		the directory hierarchy ... actually the union of the
121 *7c478bd9Sstevel@tonic-gate		three hiearchies (baseline, source and destination).
122 *7c478bd9Sstevel@tonic-gate
123 *7c478bd9Sstevel@tonic-gate		for each file, we record interesting information (type,
124 *7c478bd9Sstevel@tonic-gate		size, owner, protection, mod time) and keep separate
125 *7c478bd9Sstevel@tonic-gate		note of what these values were:
126 *7c478bd9Sstevel@tonic-gate			in the baseline last time two sides agreed
127 *7c478bd9Sstevel@tonic-gate			on the source side, as we just examined it
128 *7c478bd9Sstevel@tonic-gate			on the destination side, as we just examined it
129 *7c478bd9Sstevel@tonic-gate
130 *7c478bd9Sstevel@tonic-gate	data structures:
131 *7c478bd9Sstevel@tonic-gate
132 *7c478bd9Sstevel@tonic-gate		there is an ordered list of "base" structures
133 *7c478bd9Sstevel@tonic-gate		for each base, we maintain
134 *7c478bd9Sstevel@tonic-gate			three lists of associated "rule" descriptions:
135 *7c478bd9Sstevel@tonic-gate				inclusion rules
136 *7c478bd9Sstevel@tonic-gate				exclusion rules
137 *7c478bd9Sstevel@tonic-gate				restriction rules (from the command line)
138 *7c478bd9Sstevel@tonic-gate			a "file" tree, representing all files below the bases
139 *7c478bd9Sstevel@tonic-gate			a list of statistics to be printed as a summary
140 *7c478bd9Sstevel@tonic-gate
141 *7c478bd9Sstevel@tonic-gate		for each "rule", we maintain
142 *7c478bd9Sstevel@tonic-gate			some flags describing the type of rule
143 *7c478bd9Sstevel@tonic-gate			the character string that is the rule
144 *7c478bd9Sstevel@tonic-gate
145 *7c478bd9Sstevel@tonic-gate		for each "file", we maintain
146 *7c478bd9Sstevel@tonic-gate			sibling and child pointers to give them tree structure
147 *7c478bd9Sstevel@tonic-gate			flags to describe what we have done/should do
148 *7c478bd9Sstevel@tonic-gate			"fileinfo" information from the src, dest, and baseline
149 *7c478bd9Sstevel@tonic-gate
150 *7c478bd9Sstevel@tonic-gate			in addition there are some fields that are used
151 *7c478bd9Sstevel@tonic-gate			to add the file to a list of files requiring
152 *7c478bd9Sstevel@tonic-gate			reconciliation and record what happened to it.
153 *7c478bd9Sstevel@tonic-gate
154 *7c478bd9Sstevel@tonic-gate		a "fileinfo" structure contains a subset of the information
155 *7c478bd9Sstevel@tonic-gate		that we obtain from a stat call:
156 *7c478bd9Sstevel@tonic-gate			major/minor/inum
157 *7c478bd9Sstevel@tonic-gate			type
158 *7c478bd9Sstevel@tonic-gate			link count
159 *7c478bd9Sstevel@tonic-gate			ownership, protection, and acls
160 *7c478bd9Sstevel@tonic-gate			size
161 *7c478bd9Sstevel@tonic-gate			modification time
162 *7c478bd9Sstevel@tonic-gate
163 *7c478bd9Sstevel@tonic-gate		there is also, built up during analysis, a reconciliation
164 *7c478bd9Sstevel@tonic-gate		list.  This is an ordered list of "file" structures which
165 *7c478bd9Sstevel@tonic-gate		are believed to descibe files that have changed and require
166 *7c478bd9Sstevel@tonic-gate		reconciliation.  The ordering is important both for correctness
167 *7c478bd9Sstevel@tonic-gate		and to preserve relative modification times.
168 *7c478bd9Sstevel@tonic-gate
169 *7c478bd9Sstevel@tonic-gateOverview of passes:
170 *7c478bd9Sstevel@tonic-gate
171 *7c478bd9Sstevel@tonic-gate	pass I (evaluate)
172 *7c478bd9Sstevel@tonic-gate
173 *7c478bd9Sstevel@tonic-gate		stat every file that we might be interested in
174 *7c478bd9Sstevel@tonic-gate		(on both src/dest sides).  This includes walking
175 *7c478bd9Sstevel@tonic-gate		the trees under all directories in order to
176 *7c478bd9Sstevel@tonic-gate		find out what files exist and stating all of
177 *7c478bd9Sstevel@tonic-gate		them.
178 *7c478bd9Sstevel@tonic-gate
179 *7c478bd9Sstevel@tonic-gate		the main trick in this pass is that there may be
180 *7c478bd9Sstevel@tonic-gate		files we don't want to evaluate (because we are
181 *7c478bd9Sstevel@tonic-gate		limiting our attention to specific files and trees).
182 *7c478bd9Sstevel@tonic-gate		There is a LISTED flag kept in the database that
183 *7c478bd9Sstevel@tonic-gate		tells me whether or not I need to stat/descend any
184 *7c478bd9Sstevel@tonic-gate		given node.
185 *7c478bd9Sstevel@tonic-gate
186 *7c478bd9Sstevel@tonic-gate		all restrictions and ignores take effect during this pass.
187 *7c478bd9Sstevel@tonic-gate
188 *7c478bd9Sstevel@tonic-gate	pass II (analyze)
189 *7c478bd9Sstevel@tonic-gate
190 *7c478bd9Sstevel@tonic-gate		given the baseline and all of the current stat information
191 *7c478bd9Sstevel@tonic-gate		gained during pass I, figure out what might conceivably
192 *7c478bd9Sstevel@tonic-gate		have changed and queue it for pass III.  This pass doesn't
193 *7c478bd9Sstevel@tonic-gate		try to figure out what happened or who should win ... it
194 *7c478bd9Sstevel@tonic-gate		merely identifies candidates for pass III.  This pass
195 *7c478bd9Sstevel@tonic-gate		ignores any nodes that were not evaluated during pass I.
196 *7c478bd9Sstevel@tonic-gate
197 *7c478bd9Sstevel@tonic-gate		the queueing process, however, determines the order in
198 *7c478bd9Sstevel@tonic-gate		which the files will be processed in pass III, and the
199 *7c478bd9Sstevel@tonic-gate		order is very important.
200 *7c478bd9Sstevel@tonic-gate
201 *7c478bd9Sstevel@tonic-gate	pass III (reconcile)
202 *7c478bd9Sstevel@tonic-gate
203 *7c478bd9Sstevel@tonic-gate		process the list of candidates, figuring out what has
204 *7c478bd9Sstevel@tonic-gate		actually changed and which versions deserve to win.  If
205 *7c478bd9Sstevel@tonic-gate		is clear what needs doing, we actually do it in this
206 *7c478bd9Sstevel@tonic-gate		pass.
207 *7c478bd9Sstevel@tonic-gate
208 *7c478bd9Sstevel@tonic-gateModules
209 *7c478bd9Sstevel@tonic-gate
210 *7c478bd9Sstevel@tonic-gate	filesync.h
211 *7c478bd9Sstevel@tonic-gate		defines for limits, sizes and return codes
212 *7c478bd9Sstevel@tonic-gate		declarations for global variables (mostly cmd-line parms)
213 *7c478bd9Sstevel@tonic-gate		defines for default file names
214 *7c478bd9Sstevel@tonic-gate		declarations for routines of general interest
215 *7c478bd9Sstevel@tonic-gate
216 *7c478bd9Sstevel@tonic-gate	database.h
217 *7c478bd9Sstevel@tonic-gate		data-structures for recording rules
218 *7c478bd9Sstevel@tonic-gate		data-structures for recording information about files
219 *7c478bd9Sstevel@tonic-gate		declarations for routines that operate on/with those structures
220 *7c478bd9Sstevel@tonic-gate
221 *7c478bd9Sstevel@tonic-gate	messages.h
222 *7c478bd9Sstevel@tonic-gate		the text of all localizable messages
223 *7c478bd9Sstevel@tonic-gate
224 *7c478bd9Sstevel@tonic-gate	debug.h
225 *7c478bd9Sstevel@tonic-gate		definitions and declarations for routines for error
226 *7c478bd9Sstevel@tonic-gate		simulation and bit-map display.
227 *7c478bd9Sstevel@tonic-gate
228 *7c478bd9Sstevel@tonic-gate	acls.c
229 *7c478bd9Sstevel@tonic-gate		routines to get, set, compare, and display Access Control Lists
230 *7c478bd9Sstevel@tonic-gate	action.c
231 *7c478bd9Sstevel@tonic-gate		routines to do the real work of copying, deleting, or
232 *7c478bd9Sstevel@tonic-gate		changing ownership in order to make one side agree
233 *7c478bd9Sstevel@tonic-gate		with the other.
234 *7c478bd9Sstevel@tonic-gate	anal.c
235 *7c478bd9Sstevel@tonic-gate		routines to examine the in-core list of files and
236 *7c478bd9Sstevel@tonic-gate		determine what has changed (and therefore what is
237 *7c478bd9Sstevel@tonic-gate		files are candidates for reconciliation).  This
238 *7c478bd9Sstevel@tonic-gate		analysis includes figuring out which files should
239 *7c478bd9Sstevel@tonic-gate		be links rather than copies.
240 *7c478bd9Sstevel@tonic-gate	base.c
241 *7c478bd9Sstevel@tonic-gate		routines to read and write the baseline file
242 *7c478bd9Sstevel@tonic-gate		routines to search and manipulate the in-core base list
243 *7c478bd9Sstevel@tonic-gate	debug.c
244 *7c478bd9Sstevel@tonic-gate		data structures and routines, used to sumulate errors
245 *7c478bd9Sstevel@tonic-gate		and produce debug output, that map between bits (as found
246 *7c478bd9Sstevel@tonic-gate		in various flag words) character string names for their
247 *7c478bd9Sstevel@tonic-gate		meanings.
248 *7c478bd9Sstevel@tonic-gate
249 *7c478bd9Sstevel@tonic-gate	eval.c
250 *7c478bd9Sstevel@tonic-gate		routines to build up the internal tree that describes
251 *7c478bd9Sstevel@tonic-gate		the status of all of the files that are described
252 *7c478bd9Sstevel@tonic-gate		by the current rules.
253 *7c478bd9Sstevel@tonic-gate	files.c
254 *7c478bd9Sstevel@tonic-gate		routines to manipulate file name arguments, including
255 *7c478bd9Sstevel@tonic-gate		wild cards and embedded environment variables.
256 *7c478bd9Sstevel@tonic-gate	ignore.c
257 *7c478bd9Sstevel@tonic-gate		routines to maintain a list of names or patterns for
258 *7c478bd9Sstevel@tonic-gate		files to be ignored, and to check file names against
259 *7c478bd9Sstevel@tonic-gate		that list.
260 *7c478bd9Sstevel@tonic-gate	main.c
261 *7c478bd9Sstevel@tonic-gate		global variables, cmd-line parameter processing,
262 *7c478bd9Sstevel@tonic-gate		parameter validation, error reporting, and the
263 *7c478bd9Sstevel@tonic-gate		main loop.
264 *7c478bd9Sstevel@tonic-gate	recon.c
265 *7c478bd9Sstevel@tonic-gate		routines to examine a list of files that appear to
266 *7c478bd9Sstevel@tonic-gate		have changed, and figure out what the appropriate
267 *7c478bd9Sstevel@tonic-gate		reconciliation course of action is.
268 *7c478bd9Sstevel@tonic-gate	rename.c
269 *7c478bd9Sstevel@tonic-gate		routines to search the tree to determine whether
270 *7c478bd9Sstevel@tonic-gate		or not any creates/deletes are actually renames.
271 *7c478bd9Sstevel@tonic-gate	rules.c
272 *7c478bd9Sstevel@tonic-gate		routines to read and write the rules file
273 *7c478bd9Sstevel@tonic-gate		routines to add rules and enumerate in-core rules
274 *7c478bd9Sstevel@tonic-gate
275 *7c478bd9Sstevel@tonic-gate	filecheck.c
276 *7c478bd9Sstevel@tonic-gate		not really a part of filesync, but rather a utility
277 *7c478bd9Sstevel@tonic-gate		program that is used in the test suite.  It extracts
278 *7c478bd9Sstevel@tonic-gate		information about files that is not readily available
279 *7c478bd9Sstevel@tonic-gate		from other unix commands.
280 *7c478bd9Sstevel@tonic-gate
281 *7c478bd9Sstevel@tonic-gateComments on studying the code
282 *7c478bd9Sstevel@tonic-gate
283 *7c478bd9Sstevel@tonic-gate	if you are only interested in the "active ingredients":
284 *7c478bd9Sstevel@tonic-gate
285 *7c478bd9Sstevel@tonic-gate		read the above notes on data structures and then
286 *7c478bd9Sstevel@tonic-gate
287 *7c478bd9Sstevel@tonic-gate		read the structure declarations in database.h
288 *7c478bd9Sstevel@tonic-gate
289 *7c478bd9Sstevel@tonic-gate		read the above notes overviewing the passes
290 *7c478bd9Sstevel@tonic-gate
291 *7c478bd9Sstevel@tonic-gate		in recon.c: read reconcile
292 *7c478bd9Sstevel@tonic-gate
293 *7c478bd9Sstevel@tonic-gate			this routine almost makes sense on its own,
294 *7c478bd9Sstevel@tonic-gate			and it is unquestionably the most important
295 *7c478bd9Sstevel@tonic-gate			routine in the entire program.  Everything
296 *7c478bd9Sstevel@tonic-gate			else just gathers data for reconcile to use,
297 *7c478bd9Sstevel@tonic-gate			or updates the books to reflect the changes.
298 *7c478bd9Sstevel@tonic-gate
299 *7c478bd9Sstevel@tonic-gate		in eval.c: read evaluate, eval_file, walker, and note_info
300 *7c478bd9Sstevel@tonic-gate
301 *7c478bd9Sstevel@tonic-gate			this is the main guts of pass I
302 *7c478bd9Sstevel@tonic-gate
303 *7c478bd9Sstevel@tonic-gate		in anal.c: read analyze, check_file, check_changes & queue_file
304 *7c478bd9Sstevel@tonic-gate
305 *7c478bd9Sstevel@tonic-gate			this is the main guts of pass II
306 *7c478bd9Sstevel@tonic-gate
307 *7c478bd9Sstevel@tonic-gate	if you want to read the whole thing:
308 *7c478bd9Sstevel@tonic-gate
309 *7c478bd9Sstevel@tonic-gate		the following routines do fundamentally simple things
310 *7c478bd9Sstevel@tonic-gate		in simple ways, and can (for the most part) be understood
311 *7c478bd9Sstevel@tonic-gate		in vaccuuo.  The things they do are probably sufficiently
312 *7c478bd9Sstevel@tonic-gate		obvious that you can probably understand the more interesting
313 *7c478bd9Sstevel@tonic-gate		code without having read them at all.
314 *7c478bd9Sstevel@tonic-gate
315 *7c478bd9Sstevel@tonic-gate			base.c
316 *7c478bd9Sstevel@tonic-gate			rules.c
317 *7c478bd9Sstevel@tonic-gate			files.c
318 *7c478bd9Sstevel@tonic-gate			debug.c
319 *7c478bd9Sstevel@tonic-gate			ignore.c
320 *7c478bd9Sstevel@tonic-gate			acls.c
321 *7c478bd9Sstevel@tonic-gate
322 *7c478bd9Sstevel@tonic-gate		the following routines constitute the real meat of the
323 *7c478bd9Sstevel@tonic-gate		program, and while they are broken into specialized
324 *7c478bd9Sstevel@tonic-gate		modules, they probably need to be understood as an
325 *7c478bd9Sstevel@tonic-gate		organic whole:
326 *7c478bd9Sstevel@tonic-gate
327 *7c478bd9Sstevel@tonic-gate			main.c		setup and control
328 *7c478bd9Sstevel@tonic-gate			eval.c		pass I
329 *7c478bd9Sstevel@tonic-gate			anal.c		pass II
330 *7c478bd9Sstevel@tonic-gate			recon.c		pass III
331 *7c478bd9Sstevel@tonic-gate			action.c	execution and book-keeping
332 *7c478bd9Sstevel@tonic-gate			rename.c	a special case for a common situation
333 *7c478bd9Sstevel@tonic-gate
334 *7c478bd9Sstevel@tonic-gate
335 *7c478bd9Sstevel@tonic-gateGross calling structure / flow of control
336 *7c478bd9Sstevel@tonic-gate
337 *7c478bd9Sstevel@tonic-gate	main.c:main
338 *7c478bd9Sstevel@tonic-gate		findfiles
339 *7c478bd9Sstevel@tonic-gate		read_baseline
340 *7c478bd9Sstevel@tonic-gate		read_rules
341 *7c478bd9Sstevel@tonic-gate		if new rules
342 *7c478bd9Sstevel@tonic-gate			add_base
343 *7c478bd9Sstevel@tonic-gate			add_include
344 *7c478bd9Sstevel@tonic-gate		evaluate
345 *7c478bd9Sstevel@tonic-gate		analyze
346 *7c478bd9Sstevel@tonic-gate		write_baseline
347 *7c478bd9Sstevel@tonic-gate		write_summary
348 *7c478bd9Sstevel@tonic-gate
349 *7c478bd9Sstevel@tonic-gate	eval.c:evaluate
350 *7c478bd9Sstevel@tonic-gate		add_file_to_base
351 *7c478bd9Sstevel@tonic-gate		add_glob
352 *7c478bd9Sstevel@tonic-gate		add_run
353 *7c478bd9Sstevel@tonic-gate		ignore_pgm
354 *7c478bd9Sstevel@tonic-gate		ignore_file
355 *7c478bd9Sstevel@tonic-gate		ignore_expr
356 *7c478bd9Sstevel@tonic-gate		eval_file
357 *7c478bd9Sstevel@tonic-gate
358 *7c478bd9Sstevel@tonic-gate	eval.c:eval_file
359 *7c478bd9Sstevel@tonic-gate		note_info
360 *7c478bd9Sstevel@tonic-gate		nftw
361 *7c478bd9Sstevel@tonic-gate			walker
362 *7c478bd9Sstevel@tonic-gate				note_info
363 *7c478bd9Sstevel@tonic-gate
364 *7c478bd9Sstevel@tonic-gate	anal.c:analyze
365 *7c478bd9Sstevel@tonic-gate		check_file
366 *7c478bd9Sstevel@tonic-gate		reconcile
367 *7c478bd9Sstevel@tonic-gate
368 *7c478bd9Sstevel@tonic-gate	anal.c:check_file
369 *7c478bd9Sstevel@tonic-gate		check_changes
370 *7c478bd9Sstevel@tonic-gate		queue_file
371 *7c478bd9Sstevel@tonic-gate
372 *7c478bd9Sstevel@tonic-gate
373 *7c478bd9Sstevel@tonic-gate	recon.c:reconcile
374 *7c478bd9Sstevel@tonic-gate		samedata
375 *7c478bd9Sstevel@tonic-gate		samestuff
376 *7c478bd9Sstevel@tonic-gate		do_copy
377 *7c478bd9Sstevel@tonic-gate			copy
378 *7c478bd9Sstevel@tonic-gate			do_like
379 *7c478bd9Sstevel@tonic-gate			update_info
380 *7c478bd9Sstevel@tonic-gate		do_like
381 *7c478bd9Sstevel@tonic-gate		do_remove
382 *7c478bd9Sstevel@tonic-gate
383 *7c478bd9Sstevel@tonic-gateHelpful Hints
384 *7c478bd9Sstevel@tonic-gate
385 *7c478bd9Sstevel@tonic-gate	the "file" structure contains a bunch of flags.  Many of them
386 *7c478bd9Sstevel@tonic-gate	just summarize what we know about the file (e.g. where it was
387 *7c478bd9Sstevel@tonic-gate	found).  Others are more subtle and control the evaluation
388 *7c478bd9Sstevel@tonic-gate	process or the writing out of the baseline file.  You can't
389 *7c478bd9Sstevel@tonic-gate	really understand the processing unless you understand what
390 *7c478bd9Sstevel@tonic-gate	these flags mean.
391 *7c478bd9Sstevel@tonic-gate
392 *7c478bd9Sstevel@tonic-gate		F_NEW		added by a new rule
393 *7c478bd9Sstevel@tonic-gate
394 *7c478bd9Sstevel@tonic-gate		F_LISTED	this name was generated by a rule
395 *7c478bd9Sstevel@tonic-gate
396 *7c478bd9Sstevel@tonic-gate		F_SPARSE	this directory is an intermediate on
397 *7c478bd9Sstevel@tonic-gate				the way to a name generated by a rule
398 *7c478bd9Sstevel@tonic-gate				and should not be recursively walked.
399 *7c478bd9Sstevel@tonic-gate
400 *7c478bd9Sstevel@tonic-gate		F_EVALUATE	this node was found in evaluation and
401 *7c478bd9Sstevel@tonic-gate				has up-to-date stat information
402 *7c478bd9Sstevel@tonic-gate
403 *7c478bd9Sstevel@tonic-gate		F_CONFLICT	there is a conflict on this node so
404 *7c478bd9Sstevel@tonic-gate				baseline should remain unchanged
405 *7c478bd9Sstevel@tonic-gate
406 *7c478bd9Sstevel@tonic-gate		F_REMOVE	this node should be purged from the baseline
407 *7c478bd9Sstevel@tonic-gate
408 *7c478bd9Sstevel@tonic-gate		F_STAT_ERROR	it was impossible to stat this file
409 *7c478bd9Sstevel@tonic-gate				(and anything below it)
410 *7c478bd9Sstevel@tonic-gate
411 *7c478bd9Sstevel@tonic-gate	the implications of these flags on processing are
412 *7c478bd9Sstevel@tonic-gate
413 *7c478bd9Sstevel@tonic-gate		F_NEW, F_LISTED, F_SPARSE
414 *7c478bd9Sstevel@tonic-gate
415 *7c478bd9Sstevel@tonic-gate			affect whether or not a particular node should
416 *7c478bd9Sstevel@tonic-gate			be included in the evaluation pass.
417 *7c478bd9Sstevel@tonic-gate
418 *7c478bd9Sstevel@tonic-gate			in some situations, only new rules are interpreted.
419 *7c478bd9Sstevel@tonic-gate
420 *7c478bd9Sstevel@tonic-gate			listed files and directories should be evaluated
421 *7c478bd9Sstevel@tonic-gate			and analyzed.  sparse directories should not be
422 *7c478bd9Sstevel@tonic-gate			recursively enumerated.
423 *7c478bd9Sstevel@tonic-gate
424 *7c478bd9Sstevel@tonic-gate		F_EVALUATE
425 *7c478bd9Sstevel@tonic-gate
426 *7c478bd9Sstevel@tonic-gate			determines whether or not a node is included
427 *7c478bd9Sstevel@tonic-gate			in the analysis pass.  Only nodes that have
428 *7c478bd9Sstevel@tonic-gate			been evaluated will be analyzed.
429 *7c478bd9Sstevel@tonic-gate
430 *7c478bd9Sstevel@tonic-gate		F_CONFLICT, F_REMOVE, F_EVALUATE
431 *7c478bd9Sstevel@tonic-gate
432 *7c478bd9Sstevel@tonic-gate			affect how a node should be written back into					the baseline file.
433 *7c478bd9Sstevel@tonic-gate
434 *7c478bd9Sstevel@tonic-gate			if there is a conflict or we haven't evaluated
435 *7c478bd9Sstevel@tonic-gate			a node, we won't update the baseline.
436 *7c478bd9Sstevel@tonic-gate
437 *7c478bd9Sstevel@tonic-gate			if a node is marked for removal, it will be
438 *7c478bd9Sstevel@tonic-gate			excluded from the baseline when it is written out.
439 *7c478bd9Sstevel@tonic-gate
440 *7c478bd9Sstevel@tonic-gate		F_STAT_ERROR
441 *7c478bd9Sstevel@tonic-gate
442 *7c478bd9Sstevel@tonic-gate			if we could not get proper status information
443 *7c478bd9Sstevel@tonic-gate			about a file (or the tree under it) we cannot,
444 *7c478bd9Sstevel@tonic-gate			with any confidence, determine what its state
445 *7c478bd9Sstevel@tonic-gate			is or do anything about it.  Such files are
446 *7c478bd9Sstevel@tonic-gate			flagged as "in conflict".
447 *7c478bd9Sstevel@tonic-gate
448 *7c478bd9Sstevel@tonic-gate			it is somewhat kinky that we put error flagged
449 *7c478bd9Sstevel@tonic-gate			files on the reconciliation list.  We do this
450 *7c478bd9Sstevel@tonic-gate			because this is the easiest way to pull them
451 *7c478bd9Sstevel@tonic-gate			out for reporting as conflicts.
452 *7c478bd9Sstevel@tonic-gate
453 *7c478bd9Sstevel@tonic-gate
454