1 files changed, 179 insertions, 0 deletions
diff --git a/usr.sbin/asf/asf.8 b/usr.sbin/asf/asf.8
new file mode 100644
index 0000000..92edb4b
--- /dev/null
+++ b/usr.sbin/asf/asf.8
@@ -0,0 +1,179 @@
+.\" 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.