aa12cea2cc
Although groff_mdoc(7) gives another impression, this is the ordering most widely used and also required by mdocml/mandoc. Reviewed by: ru Approved by: philip, ed (mentors)
180 lines
4.6 KiB
Groff
180 lines
4.6 KiB
Groff
.\" Copyright (c) 2003 Greg Lehey. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" This software is provided by Greg Lehey ``as is'' and
|
|
.\" any express or implied warranties, including, but not limited to, the
|
|
.\" implied warranties of merchantability and fitness for a particular purpose
|
|
.\" are disclaimed. in no event shall Greg Lehey be liable
|
|
.\" for any direct, indirect, incidental, special, exemplary, or consequential
|
|
.\" damages (including, but not limited to, procurement of substitute goods
|
|
.\" or services; loss of use, data, or profits; or business interruption)
|
|
.\" however caused and on any theory of liability, whether in contract, strict
|
|
.\" liability, or tort (including negligence or otherwise) arising in any way
|
|
.\" out of the use of this software, even if advised of the possibility of
|
|
.\" such damage.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 20, 2006
|
|
.Dt ASF 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm asf
|
|
.Nd add symbol files
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl afKksVx
|
|
.Op Fl M Ar core
|
|
.Op Fl N Ar system
|
|
.Op Fl o Ar outfile
|
|
.Op Fl X Ar suffix
|
|
.Op Ar modules-path Op Ar outfile
|
|
.Sh DESCRIPTION
|
|
By default,
|
|
.Nm
|
|
reads
|
|
.Xr kldstat 8
|
|
output from standard input and writes to the
|
|
.Pa .asf
|
|
file a list of
|
|
.Xr gdb 1
|
|
commands to add symbol files from KLDs in subdirectories of the subdirectory
|
|
.Pa modules
|
|
of the current directory, which is intended to be a kernel build directory.
|
|
This allows
|
|
.Xr gdb 1
|
|
to load the symbols into the debugging environment.
|
|
.Pp
|
|
An optional
|
|
.Ar modules-path
|
|
argument can specify a semicolon-separated list of directory pathnames
|
|
similar to the
|
|
.Va kern.module_path
|
|
sysctl.
|
|
Each directory in the list will be searched in turn for modules.
|
|
The default list consists of just one element,
|
|
.Pa modules ,
|
|
which is suitable if the current directory is a kernel build directory.
|
|
.Pp
|
|
If
|
|
.Ar outfile
|
|
is specified,
|
|
.Nm
|
|
writes to it instead of
|
|
.Pa .asf .
|
|
If
|
|
.Ar outfile
|
|
is a single dash
|
|
.Pq Sq Fl ,
|
|
standard output is used.
|
|
.Sh OPTIONS
|
|
The following options modify the function of
|
|
.Nm :
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
When writing to an explicit
|
|
.Ar outfile ,
|
|
append to the file rather than overwriting it.
|
|
.It Fl f
|
|
Instead of trying to simplistically guess the path for each module, perform
|
|
a traversal in the same way that
|
|
.Xr find 1
|
|
does to locate an exact path for each module, no matter where in
|
|
.Ar modules-path
|
|
it is located.
|
|
.It Fl K
|
|
Instead of reading from standard input, use the conventional
|
|
system interface to get the list of modules currently loaded.
|
|
.It Fl k
|
|
Instead of reading from standard input, start a
|
|
.Xr kldstat 8
|
|
and read the information from it.
|
|
.It Fl M
|
|
Specify the core file for
|
|
.Xr kvm 3 .
|
|
Implies
|
|
.Fl V .
|
|
.It Fl N
|
|
Specify the system file for
|
|
.Xr kvm 3 .
|
|
Implies
|
|
.Fl V .
|
|
.It Fl o
|
|
Specify the file for
|
|
.Nm
|
|
to write or append its output to.
|
|
If
|
|
.Ar outfile
|
|
is a single dash
|
|
.Pq Sq Fl ,
|
|
standard output is used.
|
|
.It Fl s
|
|
Do not prepend a (guessed) subdirectory of the module path.
|
|
.It Fl V
|
|
Instead of reading from standard input, use the
|
|
.Xr kvm 3
|
|
interface to get the list of modules.
|
|
This interface allows for inspecting system crash dumps,
|
|
as well as the live system.
|
|
The
|
|
.Fl M
|
|
and
|
|
.Fl N
|
|
options will be of use if inspecting a crash dump.
|
|
Elevated privileges, e.g., those of a superuser,
|
|
may be needed to use this option.
|
|
.It Fl X
|
|
Add
|
|
.Ar suffix
|
|
to the list of suffixes
|
|
.Nm
|
|
tries to append to KLD file names.
|
|
The default list consists of
|
|
.Pa .debug ,
|
|
.Pa .symbols ,
|
|
and the null suffix.
|
|
The null suffix always stays at the list tail, after the suffix added.
|
|
Should it be needed in the middle of the list,
|
|
a blank suffix can be specified to
|
|
.Fl X
|
|
instead.
|
|
.It Fl x
|
|
Clear the list of suffixes
|
|
.Nm
|
|
tries to append to KLD file names.
|
|
Only the null suffix is left in the list.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To add symbol files from the system search path specified by the
|
|
.Va kern.module_path
|
|
sysctl, the following command can be used:
|
|
.Pp
|
|
.Dl asf -s `sysctl -n kern.module_path`
|
|
.Sh SEE ALSO
|
|
.Xr gdb 1 ,
|
|
.Xr kvm 3 ,
|
|
.Xr kld 4 ,
|
|
.Xr kldstat 8 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Fx 5.2 .
|
|
.Sh AUTHORS
|
|
.An Greg Lehey Aq grog@FreeBSD.org
|
|
.Sh BUGS
|
|
Module paths are guessed in a rather naive way by default.
|
|
It is likely to lag behind the changes to the build tree layout.
|
|
Using
|
|
.Fl f
|
|
is recommended.
|