1 .\" $NetBSD: rcorder.8,v 1.3 2000/07/17 14:16:22 mrg Exp $
4 .\" Perry E. Metzger. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgment:
16 .\" This product includes software developed for the NetBSD Project
17 .\" by Perry E. Metzger.
18 .\" 4. The name of the author may not be used to endorse or promote products
19 .\" derived from this software without specific prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 .Nd print a dependency ordering of interdependent files
49 utility is designed to print out a dependency ordering of a set of
51 Typically it is used to find an execution
52 sequence for a set of shell scripts in which certain files must be
53 executed before others.
57 must be annotated with special lines (which look like comments to the
58 shell) which indicate the dependencies the files have upon certain
59 points in the sequence, known as
61 and which indicate, for each file, which
63 may be expected to be filled by that file.
65 Within each file, a block containing a series of
72 The format of the lines is rigid.
73 Each line must begin with a single
75 followed by a single space, followed by
81 No deviation is permitted.
82 Each dependency line is then followed by a series of conditions,
83 separated by whitespace.
90 lines may appear, but all such lines must appear in a sequence without
91 any intervening lines, as once a line that does not follow the format
92 is reached, parsing stops.
93 .\" Note that for historical reasons REQUIRES, PROVIDES, and KEYWORDS
94 .\" are also accepted in addition to the above, but not documented so
95 .\" that they can be deprecated at some point in the future.
97 The options are as follows:
98 .Bl -tag -width "-k keep"
100 Produce a GraphViz (.dot) of the complete dependency graph instead of
101 plaintext calling order list.
103 Add the specified keyword to the
107 option is given, only those files containing the matching keyword are listed.
108 This option can be specified multiple times.
110 Generate ordering suitable for parallel startup, placing files that can be
111 executed simultaneously on the same line.
113 Add the specified keyword to the
117 option is given, files containing the matching keyword are not listed.
118 This option can be specified multiple times.
121 An example block follows:
122 .Bd -literal -offset indent
123 # REQUIRE: networking syslog
128 This block states that the file in which it appears depends upon the
133 conditions, and provides the
139 A file may contain zero
141 lines, in which case it provides no conditions, and may contain zero
143 lines, in which case it has no dependencies.
144 There must be at least one file with no dependencies in the set of
147 in order for it to find a starting place in the dependency ordering.
152 .Bl -tag -width "shutdown" -offset indent
153 .It Sy firstboot , nojail , nojailvnet , nostart
166 Print the dependency ordering of the services from the base system and
168 .Bd -literal -offset indent
169 $ rcorder /etc/rc.d/* /usr/local/etc/rc.d/*
172 Count the number of services in the base system, which specify the
174 keyword, while skipping those with
178 .Bd -literal -offset indent
179 $ rcorder -k nostart -s firstboot -s nojailvnet /etc/rc.d/* | wc -l
185 utility may print one of the following error messages and exit with a non-zero
186 status if it encounters an error while processing the file list.
188 .It "Requirement %s in file %s has no providers."
191 line corresponding to a condition present in a
193 line in another file.
194 .It "Circular dependency on provision %s in file %s."
195 A set of files has a circular dependency which was detected while
196 processing the stated condition.
197 Loop visualization follows this message.
198 .It "Circular dependency on file %s."
199 A set of files has a circular dependency which was detected while
200 processing the stated file.
201 .It "%s was seen in circular dependencies for %d times."
202 Each node that was a part of circular dependency loops reports total number of
204 Start with files having biggest counter when fighting with broken dependencies.
206 .Sh DIAGNOSTICS WITH GRAPHVIZ
207 Direct dependency is drawn with solid line,
209 dependency is drawn as a dashed line.
210 Each node of a graph represents an item from
213 In case there are more than one file providing an item, a list of filenames
217 Shortened filenames are also shown in case
219 item does not match file name.
221 Edges and nodes where circular dependencies were detected are drawn bold red.
222 If a file has an item in
226 that could not be provided,
227 this missing provider and the requirement will be drawn bold red as well.
239 utility first appeared in
244 .An Perry E. Metzger Aq Mt perry@piermont.com
246 .An Matthew R. Green Aq Mt mrg@eterna.com.au .
250 keyword is misleading:
251 It does not describe which daemons have to be running before a script
253 It describes which scripts must be placed before it in
254 the dependency ordering.
260 it means the script must be placed after the
262 script in the dependency ordering,
263 not necessarily that it requires
265 to be started or enabled.