d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
c35034b338
freebsd-skq/sbin/ddb/ddb.8

169 lines
4.1 KiB
Groff
Raw Normal View History

Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.\"-
Add "ddb capture print" and "ddb capture status" commands do ddb(8), alowing the DDB output capture buffer to be easily extracted from user space. Both of these commands include -M/-N arguments, allowing them to be used with kernel crash dumps (or /dev/mem). This makes it easier to use DDB scripting and output capture with minidumps or full dumps rather than with text dumps, allowing DDB output (scripted or otherwise) to be easily extracted from a crash dump. MFC after: 1 week Discussed with: brooks, jhb
2008-04-25 17:34:09 +00:00
.\" Copyright (c) 2007-2008 Robert N. M. Watson
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.\" 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 THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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$
.\"
Apply various fixes: Silence mdoc(7) warnings; Xref correct manual pages; Point user to the ddb.8 manual page. PR: 129398 Submitted by: gavin
2008-12-24 11:12:21 +00:00
.Dd December 24, 2008
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Dt DDB 8
.Os
.Sh NAME
.Nm ddb
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Nd "configure DDB kernel debugger properties"
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Sh SYNOPSIS
.Nm
Add "ddb capture print" and "ddb capture status" commands do ddb(8), alowing the DDB output capture buffer to be easily extracted from user space. Both of these commands include -M/-N arguments, allowing them to be used with kernel crash dumps (or /dev/mem). This makes it easier to use DDB scripting and output capture with minidumps or full dumps rather than with text dumps, allowing DDB output (scripted or otherwise) to be easily extracted from a crash dump. MFC after: 1 week Discussed with: brooks, jhb
2008-04-25 17:34:09 +00:00
.Cm capture
.Op Fl M core
.Op Fl N system
.Cm print
.Nm
.Cm capture
.Op Fl M core
.Op Fl N system
.Cm status
.Nm
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Cm script
.Ar scriptname
.Nm
.Cm script
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Ar scriptname Ns = Ns Ar script
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Nm
.Cm scripts
.Nm
.Cm unscript
.Ar scriptname
Add the ability to read a file of commands to ddb(8) modeled after the feature in ipfw(8).
2008-03-05 17:51:06 +00:00
.Nm
.Ar pathname
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Sh DESCRIPTION
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
The
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Nm
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
utility configures certain aspects of the
.Xr ddb 4
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
kernel debugger from user space that are not configured at compile-time or
easily via
.Xr sysctl 8
MIB entries.
Add the ability to read a file of commands to ddb(8) modeled after the feature in ipfw(8).
2008-03-05 17:51:06 +00:00
.Pp
To ease configuration, commands can be put in a file which is processed using
.Nm
as shown in the last synopsis line.
An absolute
.Ar pathname
must be used.
The file will be read line by line and applied as arguments to the
.Nm
utility.
Whitespace at the beginning of lines will be ignored as will lines where the
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
first non-whitespace character is
.Ql # .
Add "ddb capture print" and "ddb capture status" commands do ddb(8), alowing the DDB output capture buffer to be easily extracted from user space. Both of these commands include -M/-N arguments, allowing them to be used with kernel crash dumps (or /dev/mem). This makes it easier to use DDB scripting and output capture with minidumps or full dumps rather than with text dumps, allowing DDB output (scripted or otherwise) to be easily extracted from a crash dump. MFC after: 1 week Discussed with: brooks, jhb
2008-04-25 17:34:09 +00:00
.Sh OUTPUT CAPTURE
The
.Nm
utility can be used to extract the contents of the
.Xr ddb 4
output capture buffer of the current live kernel, or from the crash dump of a
kernel on disk.
The following debugger commands are available from the command line:
.Bl -tag -width indent
.It Xo
Apply various fixes: Silence mdoc(7) warnings; Xref correct manual pages; Point user to the ddb.8 manual page. PR: 129398 Submitted by: gavin
2008-12-24 11:12:21 +00:00
.Cm capture
Add "ddb capture print" and "ddb capture status" commands do ddb(8), alowing the DDB output capture buffer to be easily extracted from user space. Both of these commands include -M/-N arguments, allowing them to be used with kernel crash dumps (or /dev/mem). This makes it easier to use DDB scripting and output capture with minidumps or full dumps rather than with text dumps, allowing DDB output (scripted or otherwise) to be easily extracted from a crash dump. MFC after: 1 week Discussed with: brooks, jhb
2008-04-25 17:34:09 +00:00
.Op Fl M Ar core
.Op Fl N Ar system
.Cm print
.Xc
Print the current contents of the
.Xr ddb 4
output capture buffer.
.It Xo
Apply various fixes: Silence mdoc(7) warnings; Xref correct manual pages; Point user to the ddb.8 manual page. PR: 129398 Submitted by: gavin
2008-12-24 11:12:21 +00:00
.Cm capture
Add "ddb capture print" and "ddb capture status" commands do ddb(8), alowing the DDB output capture buffer to be easily extracted from user space. Both of these commands include -M/-N arguments, allowing them to be used with kernel crash dumps (or /dev/mem). This makes it easier to use DDB scripting and output capture with minidumps or full dumps rather than with text dumps, allowing DDB output (scripted or otherwise) to be easily extracted from a crash dump. MFC after: 1 week Discussed with: brooks, jhb
2008-04-25 17:34:09 +00:00
.Op Fl M Ar core
.Op Fl N Ar system
.Cm status
.Xc
Print the current status of the
.Xr ddb 4
output capture buffer.
Apply various fixes: Silence mdoc(7) warnings; Xref correct manual pages; Point user to the ddb.8 manual page. PR: 129398 Submitted by: gavin
2008-12-24 11:12:21 +00:00
.El
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Sh SCRIPTING
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
The
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Nm
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
utility can be used to configure aspects of
.Xr ddb 4
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
scripting from user space; scripting support is described in more detail in
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Xr ddb 4 .
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
Each of the debugger commands is available from the command line:
.Bl -tag -width indent
.It Cm script Ar scriptname
Print the script named
.Ar scriptname .
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.It Cm script Ar scriptname Ns = Ns Ar script
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
Define a script named
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Ar scriptname .
As many scripts contain characters interpreted in special ways by the shell,
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
it is advisable to enclose
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Ar script
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
in quotes.
.It Cm scripts
List currently defined scripts.
Correct subcommand name 'unset' -> 'unscript'.
2011-06-18 22:32:55 +00:00
.It Cm unscript Ar scriptname
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
Delete the script named
.Ar scriptname .
.El
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Sh EXIT STATUS
.Ex -std
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Sh EXAMPLES
The following example defines a script that will execute when the kernel
debugger is entered as a result of a break signal:
.Bd -literal -offset indent
Minor formatting tweaks. Point at ddb(4) and textdump(4) man pages for more script examples. MFC after: 3 months
2007-12-26 12:20:19 +00:00
ddb script kdb.enter.break="show pcpu; bt"
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Ed
.Pp
The following example will delete the script:
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
.Pp
.Dl "ddb unscript kdb.enter.break"
Minor formatting tweaks. Point at ddb(4) and textdump(4) man pages for more script examples. MFC after: 3 months
2007-12-26 12:20:19 +00:00
.Pp
For further examples, see the
.Xr ddb 4
and
.Xr textdump 4
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
manual pages.
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Sh SEE ALSO
Minor formatting tweaks. Point at ddb(4) and textdump(4) man pages for more script examples. MFC after: 3 months
2007-12-26 12:20:19 +00:00
.Xr ddb 4 ,
.Xr textdump 4 ,
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Xr sysctl 8
.Sh HISTORY
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
The
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Nm
- Normalize usage(), add "ddb pathname" syntax. - Revise the manpage.
2008-04-04 07:31:43 +00:00
utility first appeared in
DDB scripting, textdumps, output capture, etc, all will appear in FreeBSD 7.1 before 8.0 ships. Spotted by: Ulrich Spoerlein <uspoerlein at gmail dot com> MFC after: 3 days
2008-08-03 14:27:06 +00:00
.Fx 7.1 .
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
.Sh AUTHORS
.An Robert N M Watson
.Sh BUGS
Ideally,
.Nm
would not exist, as all pertinent aspects of
Minor formatting tweaks. Point at ddb(4) and textdump(4) man pages for more script examples. MFC after: 3 months
2007-12-26 12:20:19 +00:00
.Xr ddb 4
Add command-line tool ddb(8), which allows DDB(4) scripts to be managed from userspace. It is largely a wrapper for sysctl() calls, but because the sysctls for adding and removing scripts are awkward to use directly, this provides an easier-to-use interface. MFC after: 3 months
2007-12-26 09:38:22 +00:00
could be configured directly via
.Xr sysctl 8 .
Reference in New Issue Copy Permalink