TB(1) Domain/OS BSD TB(1)
NAME
tb - print process traceback
SYNOPSIS
tb [options] [process_spec]
DESCRIPTION
tb prints a process traceback, listing the name and current line number
of each routine on the call stack. There are two forms of traceback:
Active Traces the current state of an executing process.
Diagnostic
Traces the state of an aborted process at the time of the fault
which killed it.
process_spec (optional)
UNIX process ID (PID), aegis process name, or aegis
process UID. Process names are not recorded in the
process dump file, so dead processes must be referenced by
PID or UID. Since PID's are reused multiple dump file
entries for the same PID are possible, the command will
select the most recent.
Default if omitted: perform a diagnostic traceback for the
last child of the invoking process
OPTIONS
-p[roc] Traces exactly the specified process. If this option is
absent, the specified process or one of its children may
be traced, as described below.
-d[iagnostic] Prints a diagnostic traceback of an aborted process.
-n[ode] node_spec
Uses the process dump file on the specified node. Implies
-diagnostic.
-c[ommand] pathname
Prints diagnostic traceback(s) for processes running the
specified program. pathname must be reachable from the
working directory; command search rules are not applied.
Implies -diagnostic.
-s[ince] date_time_spec
Prints diagnostic traceback(s) for processes which aborted
after the specified time. Implies -diagnostic. The format
for date_time_spec is [[[yyyy/]mm/dd][.][hh:mm[:ss]].
-l[ast] [n] Prints the n most recent entries in the process dump file
(which also satisfy other selection criteria if given). n
defaults to 1. If neither -last nor -all is specified tb
prints only the most recent entry. Implies -diagnostic.
-a[ll] Prints all entries in the process dump file (which also
satisfy other selection criteria if given.) If neither
-last or -all are specified, tb prints only the most
recent entry. Implies -diagnostic.
-f[ull] Prints additional fault diagnostic information, such as
register values. Implies -diagnostic.
-b[rief] Lists entries in the process dump file that satisfy
selection criteria, but do not print tracebacks. The
listing shows the process, parent, and group IDs, the time
of the dump, the abort status, and the program that was
running.
-t[asks] Traces all tasks in the process. By default only the
currently active task is shown. Ignored if tasking is not
enabled. Applies only to active process tracebacks.
-m Trace all threads in the process. Applies only to active
process tracebacks.
-h[eaders_off] Suppresses output of process ID, dump time, and program
name preceding diagnostic traceback, or of column headers
in brief format. It has no effect on active process
traceback.
Diagnostic Tracebacks
A diagnostic traceback shows the state of the call stack at the time of a
fault which causes a process to be aborted. Traceback information is
written to `node_data/system_logs/proc_dump at the time of the fault.
This is a circular buffer in which the oldest information is overwritten
as needed to make room for new. There is space for approximately 150-200
dumps. tb prints up to 128 call levels for diagnostic tracebacks.
tb prints a diagnostic traceback if the command line specifies
-diagnostic or any option which implies it, or if the process specified
is not active. If -diagnostic is specified together with an active
process, the most recent aborted child of that process is traced (or most
recent children if -last or -all is specified).
If no options are given (except possibly -f, -b or -h) tb prints a
diagnostic traceback for the most recent aborted child of the process
which invoked tb.
Examples of Requesting Diagnostic Tracebacks
Assume process_5 is an active shell process, and process number 107 is
not active. Traceback process 107.
$ tb 107
Traceback last aborted command invoked from process_5.
$ tb -d process_5
Traceback last aborted command from this shell
$ tb
Traceback last aborted process running test3
$ tb -c test3
List all entries in the process dump file made today
$ tb -s today -a -b
Active Process Tracebacks
An active process traceback shows the current state of an executing
process, listing the name and line number of each procedure in the call
stack. The process is suspended while the traceback is taken. tb prints
an active process traceback if the command line specifies an active
process and does not include -diagnostic (or any option that implies it).
If the process is specified by name and has any active children, then the
most recent child is traced. (This allows a process to be specified by
the name of its invoking shell process.) This behavior may be overriden
by the -proc switch, or by specifying the process by PID or UID. Note
that the only other option applicable to active process tracebacks is
-task or -m (multi-threads).
Examples of Requesting Active Process Tracebacks
Assume process_7 is an active shell process, from which a command running
in process 747 has been invoked.
$ tb 747
Traceback the invoked command
$ tb process_7
same
$ tb -p process_7
Traceback the shell process itself