1.\" $NetBSD: rcorder.8,v 1.3 2000/07/17 14:16:22 mrg Exp $ 2.\" 3.\" Copyright (c) 1998 4.\" Perry E. Metzger. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 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. 20.\" 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. 31.\" 32.\" $FreeBSD$ 33.\" 34.Dd June 22, 2020 35.Dt RCORDER 8 36.Os 37.Sh NAME 38.Nm rcorder 39.Nd print a dependency ordering of interdependent files 40.Sh SYNOPSIS 41.Nm 42.Op Fl k Ar keep 43.Op Fl s Ar skip 44.Ar 45.Sh DESCRIPTION 46The 47.Nm 48utility is designed to print out a dependency ordering of a set of 49interdependent files. 50Typically it is used to find an execution 51sequence for a set of shell scripts in which certain files must be 52executed before others. 53.Pp 54Each file passed to 55.Nm 56must be annotated with special lines (which look like comments to the 57shell) which indicate the dependencies the files have upon certain 58points in the sequence, known as 59.Dq conditions , 60and which indicate, for each file, which 61.Dq conditions 62may be expected to be filled by that file. 63.Pp 64Within each file, a block containing a series of 65.Ql REQUIRE , 66.Ql PROVIDE , 67.Ql BEFORE 68and 69.Ql KEYWORD 70lines must appear. 71The format of the lines is rigid. 72Each line must begin with a single 73.Ql # , 74followed by a single space, followed by 75.Ql PROVIDE\&: , 76.Ql REQUIRE\&: , 77.Ql BEFORE\&: , 78or 79.Ql KEYWORD\&: . 80No deviation is permitted. 81Each dependency line is then followed by a series of conditions, 82separated by whitespace. 83Multiple 84.Ql PROVIDE , 85.Ql REQUIRE , 86.Ql BEFORE 87and 88.Ql KEYWORD 89lines may appear, but all such lines must appear in a sequence without 90any intervening lines, as once a line that does not follow the format 91is reached, parsing stops. 92.\" Note that for historical reasons REQUIRES, PROVIDES, and KEYWORDS 93.\" are also accepted in addition to the above, but not documented so 94.\" that they can be deprecated at some point in the future. 95.Pp 96The options are as follows: 97.Bl -tag -width "-k keep" 98.It Fl k Ar keep 99Add the specified keyword to the 100.Dq "keep list" . 101If any 102.Fl k 103option is given, only those files containing the matching keyword are listed. 104This option can be specified multiple times. 105.It Fl s Ar skip 106Add the specified keyword to the 107.Dq "skip list" . 108If any 109.Fl s 110option is given, files containing the matching keyword are not listed. 111This option can be specified multiple times. 112.El 113.Pp 114An example block follows: 115.Bd -literal -offset indent 116# REQUIRE: networking syslog 117# REQUIRE: usr 118# PROVIDE: dns nscd 119.Ed 120.Pp 121This block states that the file in which it appears depends upon the 122.Ql networking , 123.Ql syslog , 124and 125.Ql usr 126conditions, and provides the 127.Ql dns 128and 129.Ql nscd 130conditions. 131.Pp 132A file may contain zero 133.Ql PROVIDE 134lines, in which case it provides no conditions, and may contain zero 135.Ql REQUIRE 136lines, in which case it has no dependencies. 137There must be at least one file with no dependencies in the set of 138arguments passed to 139.Nm 140in order for it to find a starting place in the dependency ordering. 141.Sh KEYWORDS 142There are several 143.Em KEYWORDs 144in use: 145.Bl -tag -width "shutdown" -offset indent 146.It Sy firstboot , nojail , nojailvnet , nostart 147Used by 148.Xr rc 8 . 149.It Sy resume 150Used by 151.Nm /etc/rc.resume 152(see 153.Xr acpiconf 8 ) 154.It Sy shutdown 155Used by 156.Xr rc.shutdown 8 . 157.El 158.Sh EXAMPLES 159Print the dependency ordering of the services from the base system and 160.Xr ports 7 : 161.Bd -literal -offset indent 162$ rcorder /etc/rc.d/* /usr/local/etc/rc.d/* 163.Ed 164.Pp 165Count the number of services in the base system, which specify the 166.Sy shutdown 167keyword, while skipping those with 168.Sy firstboot 169and 170.Sy nojailvnet : 171.Bd -literal -offset indent 172$ rcorder -k nostart -s firstboot -s nojailvnet /etc/rc.d/* | wc -l 173 3 174.Ed 175.Sh DIAGNOSTICS 176The 177.Nm 178utility may print one of the following error messages and exit with a non-zero 179status if it encounters an error while processing the file list. 180.Bl -diag 181.It "Requirement %s has no providers, aborting." 182No file has a 183.Ql PROVIDE 184line corresponding to a condition present in a 185.Ql REQUIRE 186line in another file. 187.It "Circular dependency on provision %s, aborting." 188A set of files has a circular dependency which was detected while 189processing the stated condition. 190.It "Circular dependency on file %s, aborting." 191A set of files has a circular dependency which was detected while 192processing the stated file. 193.El 194.Sh SEE ALSO 195.Xr acpiconf 8 , 196.Xr rc 8 , 197.Xr rc.shutdown 8 , 198.Xr service 8 199.Sh HISTORY 200The 201.Nm 202utility appeared in 203.Nx 1.5 . 204.Nm 205utility first appeared in 206.Fx 5.0 . 207.Sh AUTHORS 208.An -nosplit 209Written by 210.An Perry E. Metzger Aq Mt perry@piermont.com 211and 212.An Matthew R. Green Aq Mt mrg@eterna.com.au . 213.Sh BUGS 214The 215.Ql REQUIRE 216keyword is misleading: 217It does not describe which daemons have to be running before a script 218will be started. 219It describes which scripts must be placed before it in 220the dependency ordering. 221For example, 222if your script has a 223.Ql REQUIRE 224on 225.Ql sshd , 226it means the script must be placed after the 227.Ql sshd 228script in the dependency ordering, 229not necessarily that it requires 230.Nm sshd 231to be started or enabled. 232