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 DESCRIPTION 41By default, 42.Nm 43reads 44.Xr kldstat 8 45output from standard input and writes to the 46.Pa .asf 47file a list of 48.Xr gdb 1 49commands to add symbol files from KLDs in subdirectories of the subdirectory 50.Pa modules 51of the current directory, which is intended to be a kernel build directory. 52This allows 53.Xr gdb 1 54to load the symbols into the debugging environment. 55.Pp 56An optional 57.Ar modules-path 58argument can specify a semicolon-separated list of directory pathnames 59similar to the 60.Va kern.module_path 61sysctl. 62Each directory in the list will be searched in turn for modules. 63The default list consists of just one element, 64.Pa modules , 65which is suitable if the current directory is a kernel build directory. 66.Pp 67If 68.Ar outfile 69is specified, 70.Nm 71writes to it instead of 72.Pa .asf . 73If 74.Ar outfile 75is a single dash 76.Pq Sq Fl , 77standard output is used. 78.Sh OPTIONS 79The following options modify the function of 80.Nm : 81.Bl -tag -width indent 82.It Fl a 83When writing to an explicit 84.Ar outfile , 85append to the file rather than overwriting it. 86.It Fl f 87Instead of trying to simplistically guess the path for each module, perform 88a traversal in the same way that 89.Xr find 1 90does to locate an exact path for each module, no matter where in 91.Ar modules-path 92it is located. 93.It Fl K 94Instead of reading from standard input, use the conventional 95system interface to get the list of modules currently loaded. 96.It Fl k 97Instead of reading from standard input, start a 98.Xr kldstat 8 99and read the information from it. 100.It Fl M 101Specify the core file for 102.Xr kvm 3 . 103Implies 104.Fl V . 105.It Fl N 106Specify the system file for 107.Xr kvm 3 . 108Implies 109.Fl V . 110.It Fl o 111Specify the file for 112.Nm 113to write or append its output to. 114If 115.Ar outfile 116is a single dash 117.Pq Sq Fl , 118standard output is used. 119.It Fl s 120Do not prepend a (guessed) subdirectory of the module path. 121.It Fl V 122Instead of reading from standard input, use the 123.Xr kvm 3 124interface to get the list of modules. 125This interface allows for inspecting system crash dumps, 126as well as the live system. 127The 128.Fl M 129and 130.Fl N 131options will be of use if inspecting a crash dump. 132Elevated privileges, e.g., those of a superuser, 133may be needed to use this option. 134.It Fl X 135Add 136.Ar suffix 137to the list of suffixes 138.Nm 139tries to append to KLD file names. 140The default list consists of 141.Pa .debug , 142.Pa .symbols , 143and the null suffix. 144The null suffix always stays at the list tail, after the suffix added. 145Should it be needed in the middle of the list, 146a blank suffix can be specified to 147.Fl X 148instead. 149.It Fl x 150Clear the list of suffixes 151.Nm 152tries to append to KLD file names. 153Only the null suffix is left in the list. 154.El 155.Sh EXAMPLES 156To add symbol files from the system search path specified by the 157.Va kern.module_path 158sysctl, the following command can be used: 159.Pp 160.Dl asf -s `sysctl -n kern.module_path` 161.Sh SEE ALSO 162.Xr gdb 1 , 163.Xr kvm 3 , 164.Xr kld 4 , 165.Xr kldstat 8 , 166.Xr sysctl 8 167.Sh HISTORY 168The 169.Nm 170utility first appeared in 171.Fx 5.2 . 172.Sh AUTHORS 173.An Greg Lehey Aq Mt grog@FreeBSD.org 174.Sh BUGS 175Module paths are guessed in a rather naive way by default. 176It is likely to lag behind the changes to the build tree layout. 177Using 178.Fl f 179is recommended. 180