sbin/rcorder/rcorder.8

   1 .\"     $NetBSD: rcorder.8,v 1.3 2000/07/17 14:16:22 mrg Exp $
   2 .\"     $DragonFly: src/sbin/rcorder/rcorder.8,v 1.5 2007/07/28 10:37:22 swildner Exp $
   3 .\"
   4 .\" Copyright (c) 1998
   5 .\"     Perry E. Metzger.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgment:
  17 .\"     This product includes software developed for the NetBSD Project
  18 .\"     by Perry E. Metzger.
  19 .\" 4. The name of the author may not be used to endorse or promote products
  20 .\"    derived from this software without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  23 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  25 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  27 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  31 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .\" $FreeBSD: src/sbin/rcorder/rcorder.8,v 1.3 2002/11/25 16:23:03 ru Exp $
  34 .\"
  35 .Dd July 28, 2007
  36 .Dt RCORDER 8
  37 .Os
  38 .Sh NAME
  39 .Nm rcorder
  40 .Nd print a dependency ordering of interdependent files
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl k Ar keep
  44 .Op Fl s Ar skip
  45 .Op Fl o Ar keyword
  46 .Op Fl p
  47 .Ar
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility is designed to print out a dependency ordering of a set of
  52 interdependent files.
  53 Typically it is used to find an execution
  54 sequence for a set of shell scripts in which certain files must be
  55 executed before others.
  56 .Pp
  57 Each file passed to
  58 .Nm
  59 must be annotated with special lines (which look like comments to the
  60 shell) which indicate the dependencies the files have upon certain
  61 points in the sequence, known as
  62 .Dq conditions ,
  63 and which indicate, for each file, which
  64 .Dq conditions
  65 may be expected to be filled by that file.
  66 .Pp
  67 Within each file, a block containing a series of
  68 .Dq Li REQUIRE ,
  69 .Dq Li PROVIDE ,
  70 .Dq Li BEFORE
  71 and
  72 .Dq Li KEYWORD
  73 lines must appear.
  74 The format of the lines is rigid.
  75 Each line must begin with a single
  76 .Ql # ,
  77 followed by a single space, followed by
  78 .Dq Li PROVIDE: ,
  79 .Dq Li REQUIRE: ,
  80 .Dq Li BEFORE: ,
  81 or
  82 .Dq Li KEYWORD: .
  83 No deviation is permitted.
  84 Each dependency line is then followed by a series of conditions,
  85 separated by whitespace.
  86 Multiple
  87 .Dq Li PROVIDE ,
  88 .Dq Li REQUIRE ,
  89 .Dq Li BEFORE
  90 and
  91 .Dq Li KEYWORD
  92 lines may appear, but all such lines must appear in a sequence without
  93 any intervening lines, as once a line that does not follow the format
  94 is reached, parsing stops.
  95 .Pp
  96 The options are as follows:
  97 .Bl -tag -width indent
  98 .It Fl k
  99 Add the specified keyword to the
 100 .Dq "keep list" .
 101 If any
 102 .Fl k
 103 option is given, only those files containing the matching keyword are listed.
 104 .It Fl s
 105 Add the specified keyword to the
 106 .Dq "skip list" .
 107 If any
 108 .Fl s
 109 option is given, files containing the matching keyword are not listed.
 110 .It Fl o
 111 Generate the dependency list required to activate the specified
 112 .Ar keyword ,
 113 including the file providing
 114 .Ar keyword .
 115 If several
 116 .Fl o
 117 options are specified, the results are merged.
 118 .It Fl p
 119 Output the list of provided keywords for the specified files.
 120 .El
 121 .Pp
 122  An example block follows:
 123 .Bd -literal -offset indent
 124 # REQUIRE: networking syslog
 125 # REQUIRE: usr
 126 # PROVIDE: dns nscd
 127 .Ed
 128 .Pp
 129 This block states that the file in which it appears depends upon the
 130 .Dq Li networking ,
 131 .Dq Li syslog ,
 132 and
 133 .Dq Li usr
 134 conditions, and provides the
 135 .Dq Li dns
 136 and
 137 .Dq Li nscd
 138 conditions.
 139 .Pp
 140 A file may contain zero
 141 .Dq Li PROVIDE
 142 lines, in which case it provides no conditions, and may contain zero
 143 .Dq Li REQUIRE
 144 lines, in which case it has no dependencies.
 145 There must be at least one file with no dependencies in the set of
 146 arguments passed to
 147 .Nm
 148 in order for it to find a starting place in the dependency ordering.
 149 .Sh DIAGNOSTICS
 150 The
 151 .Nm
 152 utility may print one of the following error messages and exit with a non-zero
 153 status if it encounters an error while processing the file list.
 154 .Bl -diag
 155 .It "Requirement %s has no providers, aborting."
 156 No file has a
 157 .Dq Li PROVIDE
 158 line corresponding to a condition present in a
 159 .Dq Li REQUIRE
 160 line in another file.
 161 .It "Circular dependency on provision %s, aborting."
 162 A set of files has a circular dependency which was detected while
 163 processing the stated condition.
 164 .It "Circular dependency on file %s, aborting."
 165 A set of files has a circular dependency which was detected while
 166 processing the stated file.
 167 .El
 168 .Sh SEE ALSO
 169 .Xr rc 8
 170 .Sh HISTORY
 171 The
 172 .Nm
 173 utility first appeared in
 174 .Nx 1.5 .
 175 .Sh AUTHORS
 176 .An -nosplit
 177 Written by
 178 .An Perry E. Metzger Aq perry@piermont.com
 179 and
 180 .An Matthew R. Green Aq mrg@eterna.com.au .