tools/tools/sysdoc/sysdoc.sh

   1 #!/bin/sh
   2 #
   3 #
   4 #################################################################
   5 # Missing Features:
   6 # It would be nice to have OIDs separated into composite groups
   7 # using the subsection mdoc(7) feature (.Ss) without adding extra
   8 # files.
   9 #
  10 # The ability to notice when new OIDs are added to FreeBSD, and
  11 # and the automation of their sorting and addition into the
  12 # tunables.mdoc file.
  13 #
  14 # Perhaps a re-implementation in C?  This wouldn't be much of
  15 # a challenge for the right individual but it may require a lot
  16 # of changes to sysctl.h.  Eventually this utility should replace
  17 # documenting sysctls in code and manual pages since this utility
  18 # creates a manual page dynamicly based on the kernel.  This
  19 # would kill duplication between manual pages and kernel code as
  20 # well as improve the removal of sysctls when they are obsoleted.
  21 #################################################################
  22
  23 # Set our path up.
  24 PATH=/bin:/usr/bin:/sbin:/usr/sbin
  25
  26 # Set a unique date format in the produced manual page.
  27 DATE=`LC_TIME=C date +"%B %d, %Y"`
  28
  29 # We need a usage statement correct?
  30 USAGE="Usage: run.sh -k [absolute path]"
  31
  32 # The endman function closes the list and adds the bottom
  33 # part of our manual page.
  34 endman() {
  35 cat <<EOF>> ./sysctl.5
  36 .El
  37 .Sh IMPLEMENTATION NOTES
  38 This manual page has been automatically generated by
  39 a set of scripts written in
  40 .Xr sh 1 .
  41 The
  42 .Xr mdoc 7
  43 markup is stored in the database file and extracted
  44 accordingly when invoked.
  45 For information on the
  46 .Xr sysctl 8
  47 implementation, see the respecting manual pages.
  48 .Sh SEE ALSO
  49 .Xr loader.conf 5 ,
  50 .Xr rc.conf 5 ,
  51 .Xr sysctl.conf 5 ,
  52 .Xr boot 8 ,
  53 .Xr loader 8 ,
  54 .Xr sysctl 8 ,
  55 .Xr sysctl_add_oid 9 ,
  56 .Xr sysctl_ctx_init 9
  57 .Sh AUTHORS
  58 This manual page is automatically generated
  59 by a set of scripts written by
  60 .An -nosplit
  61 .An Tom Rhodes Aq Mt trhodes@FreeBSD.org ,
  62 with significant contributions from
  63 .An Giorgos Keramidas Aq Mt keramida@FreeBSD.org ,
  64 .An Ruslan Ermilov Aq Mt ru@FreeBSD.org ,
  65 and
  66 .An Marc Silver Aq Mt marcs@draenor.org .
  67 .Sh BUGS
  68 Sometimes
  69 .Fx
  70 .Nm sysctls
  71 can be left undocumented by those who originally
  72 implemented them.
  73 This script was forged as a way to automatically
  74 produce a manual page to aid in the administration and
  75 configuration of a
  76 .Fx
  77 system.
  78 It also gets around adding a bunch of supporting code to the
  79 .Nm
  80 interface.
  81 EOF
  82 }
  83
  84 # The markup_create() function builds the actual
  85 # markup file to be dropped into.  In essence,
  86 # compare our list of tunables with the documented
  87 # tunables in our tunables.mdoc file and generate
  88 # the final 'inner circle' of our manual page.
  89 markup_create() {
  90         sort -u  < _names |             \
  91         xargs -n 1 /bin/sh ./sysctl.sh  \
  92                 > markup.file           \
  93                 2> tunables.TODO
  94         rm _names
  95 }
  96
  97 # Finally, the following lines will call our functions and
  98 # and create our document using the following function:
  99 page_create() {
 100         startman
 101         /bin/cat ./markup.file >> sysctl.5
 102         endman
 103 }
 104
 105 # The startman function creates the initial mdoc(7) formatted
 106 # manual page.  This is required before we populate it with
 107 # tunables both loader and sysctl(8) oids.
 108 startman() {
 109 cat <<EOF>> ./sysctl.5
 110 .\"
 111 .\" Copyright (c) 2005 Tom Rhodes
 112 .\" All rights reserved.
 113 .\"
 114 .\" Redistribution and use in source and binary forms, with or without
 115 .\" modification, are permitted provided that the following conditions
 116 .\" are met:
 117 .\" 1. Redistribution of source code must retain the above copyright
 118 .\"    notice, this list of conditions and the following disclaimer.
 119 .\" 2. Redistribution's in binary form must reproduce the above copyright
 120 .\"    notice, this list of conditions and the following disclaimer in the
 121 .\"    documentation and/or other materials provided with the distribution.
 122 .\"
 123 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 124 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 125 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 126 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 127 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 128 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 129 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 130 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 131 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 132 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 133 .\" SUCH DAMAGE.
 134 .\"
 135 .\"
 136 .Dd $DATE
 137 .Dt SYSCTL 5
 138 .Os
 139 .Sh NAME
 140 .Nm sysctl
 141 .Nd "list of available syctls based on kernel configuration"
 142 .Sh DESCRIPTION
 143 .Fx
 144 supports kernel alterations on the fly or at
 145 system initialization by using a feature
 146 known as a
 147 .Nm
 148 and a database.
 149 Many values may be altered simply by using the
 150 .Xr sysctl 8
 151 utility followed by a
 152 .Nm
 153 and its new value at the command prompt.
 154 For example:
 155 .Dl sysctl kern.ipc.zero_copy.receive=1
 156 will enable zero copy sockets for receive.
 157 .Pp
 158 Many variables may only be available if specific kernel
 159 options are built into the kernel.
 160 For example, the previous
 161 .Nm
 162 requires
 163 .Xr zero_copy 9 .
 164 .Pp
 165 Most of these values only offer an enable/disable
 166 option, altered by using a numerical value of
 167 .Dq 0
 168 or
 169 .Dq 1
 170 where the former is disable and latter is enable.
 171 Other cases the
 172 .Nm
 173 may require a string value.
 174 The
 175 .Xr sysctl 8
 176 utility may be used to dump a list of current
 177 values which should provide an example of
 178 the non-numeric cases.
 179 .Pp
 180 In cases where the value may not be altered, the
 181 following warning will be issued:
 182 .Dq read only value
 183 and the
 184 .Nm
 185 will not be changed.
 186 To alter these values, the administrator may place
 187 them in the
 188 .Xr sysctl.conf 5
 189 file.
 190 This will invoke the changes during
 191 system initialization for those values
 192 which may be altered.
 193 In other cases, the
 194 .Xr loader.conf 5
 195 may be used.
 196 Then again, some of these
 197 .Nm sysctls
 198 may never be altered.
 199 .Pp
 200 The
 201 .Nm
 202 supported by
 203 .Xr sysctl 8
 204 are:
 205 .Pp
 206 .Bl -ohang -offset indent
 207 EOF
 208 }
 209
 210 #
 211 # The nm(1) utility must only be used on the architecture which
 212 # we build it for.  Although i386 is so; my only fear
 213 # with this is that this will not work properly on cross-builds.
 214
 215 while getopts k FLAG;
 216   do
 217     case "$FLAG" in
 218
 219         k)  LOCATION="$OPTARG" ;;
 220
 221         *)  echo "$USAGE"
 222             exit 0 ;;
 223
 224   esac
 225 done
 226
 227 # The k flag
 228 shift
 229
 230 if [ -z "$1" ] && [ -z "$LOCATION" ] ;
 231   then echo "Malformed or improper path specified";
 232   exit 1;
 233 fi
 234
 235 if [ -z "$LOCATION" ] ;
 236   then LOCATION="$1" \
 237     && for x in `find $LOCATION -name '*.kld'`  \
 238         $LOCATION/kernel;                       \
 239         do nm $x |                              \
 240         sed -n '/sysctl___/ {
 241                 's/[\.a-z_]*sysctl___//g'
 242                 's/_/./g'
 243                 p
 244         }' |                                    \
 245         awk {'print $3'} |                      \
 246         sort -u > _names;
 247         done;
 248         markup_create
 249         page_create
 250 fi