usr.sbin/asf/asf.8

   1 .\" Copyright (c) 2003 Greg Lehey.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Greg Lehey ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Greg Lehey be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd December 20, 2006
  27 .Dt ASF 8
  28 .Os
  29 .Sh NAME
  30 .Nm asf
  31 .Nd add symbol files
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl afKksVx
  35 .Op Fl M Ar core
  36 .Op Fl N Ar system
  37 .Op Fl o Ar outfile
  38 .Op Fl X Ar suffix
  39 .Op Ar modules-path Op Ar outfile
  40 .Sh DEPRECATION NOTICE
  41 The
  42 .Nm
  43 utility is not present in
  44 .Fx 12.0
  45 and later.
  46 The
  47 .Xr kgdb 1
  48 debugger handles kernel module state internally.
  49 .Sh DESCRIPTION
  50 By default,
  51 .Nm
  52 reads
  53 .Xr kldstat 8
  54 output from standard input and writes to the
  55 .Pa .asf
  56 file a list of
  57 .Xr gdb 1
  58 commands to add symbol files from KLDs in subdirectories of the subdirectory
  59 .Pa modules
  60 of the current directory, which is intended to be a kernel build directory.
  61 This allows
  62 .Xr gdb 1
  63 to load the symbols into the debugging environment.
  64 .Pp
  65 An optional
  66 .Ar modules-path
  67 argument can specify a semicolon-separated list of directory pathnames
  68 similar to the
  69 .Va kern.module_path
  70 sysctl.
  71 Each directory in the list will be searched in turn for modules.
  72 The default list consists of just one element,
  73 .Pa modules ,
  74 which is suitable if the current directory is a kernel build directory.
  75 .Pp
  76 If
  77 .Ar outfile
  78 is specified,
  79 .Nm
  80 writes to it instead of
  81 .Pa .asf .
  82 If
  83 .Ar outfile
  84 is a single dash
  85 .Pq Sq Fl ,
  86 standard output is used.
  87 .Sh OPTIONS
  88 The following options modify the function of
  89 .Nm :
  90 .Bl -tag -width indent
  91 .It Fl a
  92 When writing to an explicit
  93 .Ar outfile ,
  94 append to the file rather than overwriting it.
  95 .It Fl f
  96 Instead of trying to simplistically guess the path for each module, perform
  97 a traversal in the same way that
  98 .Xr find 1
  99 does to locate an exact path for each module, no matter where in
 100 .Ar modules-path
 101 it is located.
 102 .It Fl K
 103 Instead of reading from standard input, use the conventional
 104 system interface to get the list of modules currently loaded.
 105 .It Fl k
 106 Instead of reading from standard input, start a
 107 .Xr kldstat 8
 108 and read the information from it.
 109 .It Fl M
 110 Specify the core file for
 111 .Xr kvm 3 .
 112 Implies
 113 .Fl V .
 114 .It Fl N
 115 Specify the system file for
 116 .Xr kvm 3 .
 117 Implies
 118 .Fl V .
 119 .It Fl o
 120 Specify the file for
 121 .Nm
 122 to write or append its output to.
 123 If
 124 .Ar outfile
 125 is a single dash
 126 .Pq Sq Fl ,
 127 standard output is used.
 128 .It Fl s
 129 Do not prepend a (guessed) subdirectory of the module path.
 130 .It Fl V
 131 Instead of reading from standard input, use the
 132 .Xr kvm 3
 133 interface to get the list of modules.
 134 This interface allows for inspecting system crash dumps,
 135 as well as the live system.
 136 The
 137 .Fl M
 138 and
 139 .Fl N
 140 options will be of use if inspecting a crash dump.
 141 Elevated privileges, e.g., those of a superuser,
 142 may be needed to use this option.
 143 .It Fl X
 144 Add
 145 .Ar suffix
 146 to the list of suffixes
 147 .Nm
 148 tries to append to KLD file names.
 149 The default list consists of
 150 .Pa .debug ,
 151 .Pa .symbols ,
 152 and the null suffix.
 153 The null suffix always stays at the list tail, after the suffix added.
 154 Should it be needed in the middle of the list,
 155 a blank suffix can be specified to
 156 .Fl X
 157 instead.
 158 .It Fl x
 159 Clear the list of suffixes
 160 .Nm
 161 tries to append to KLD file names.
 162 Only the null suffix is left in the list.
 163 .El
 164 .Sh EXAMPLES
 165 To add symbol files from the system search path specified by the
 166 .Va kern.module_path
 167 sysctl, the following command can be used:
 168 .Pp
 169 .Dl asf -s `sysctl -n kern.module_path`
 170 .Sh SEE ALSO
 171 .Xr gdb 1 ,
 172 .Xr kvm 3 ,
 173 .Xr kld 4 ,
 174 .Xr kldstat 8 ,
 175 .Xr sysctl 8
 176 .Sh HISTORY
 177 The
 178 .Nm
 179 utility first appeared in
 180 .Fx 5.2 .
 181 .Sh AUTHORS
 182 .An Greg Lehey Aq Mt grog@FreeBSD.org
 183 .Sh BUGS
 184 Module paths are guessed in a rather naive way by default.
 185 It is likely to lag behind the changes to the build tree layout.
 186 Using
 187 .Fl f
 188 is recommended.