tools/tools/sysdoc/sysdoc.sh

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