/usr/dt/share/man/cat1/tttrace.1(/usr/dt/share/man/cat1/tttrace.1)
tttrace(1) USER COMMANDS tttrace(1)
NAME
tttrace - trace ToolTalk calls and messages
SYNOPSIS
tttrace [-0FCa] [-o outfile ] [-S session | command]
tttrace [-e script | -f scriptfile ] [-S session | command]
DESCRIPTION
tttrace traces message traffic through the server for the
indicated ToolTalk session, or runs command with ToolTalk
client tracing turned on. If neither session nor command is
given, the default session is traced. By default, tracing
terminates when tttrace exits.
Tracing of ToolTalk functions looks like this:
[pid] function_name(params) = return_value (Tt_status)
With the -a option, message attributes are printed after a
one-line summary of the message:
Tt_state Tt_paradigm Tt_class (Tt_disposition in Tt_scope): status == Tt_status
State changes are indicated by:
old_state => new_state.
Deliveries are indicated by:
Tt_message => procid <recipient_procid>
When dispatching is being traced, the reason for each
dispatch is one of:
tt_message_send()
tt_message_reject()
tt_message_fail()
tt_message_reply()
tt_session_join()
tt_file_join()
tt_message_reply()
A client called the indicated function.
tt_message_send_on_exit()
ttsession is dispatching on_exit messages for a
client that disconnected before calling tt_close().
tt_message_accept()
ttsession is dispatching messages that had been
blocked while a ptype was being started. The
started client has now called either
tt_message_accept() or tt_message_reply() to indi-
cate that the ptype should be unblocked.
TT_ERR_PTYPE_START
A ptype instance was started to receive the message,
Unix System LaboratLastschange: 19 January 1994 1
tttrace(1) USER COMMANDS tttrace(1)
but the start command exited before it connected to
ttsession.
TT_ERR_PROCID
ttsession lost its connection to the client that was
working on this request.
ttsession -> ttsession
Another session wants this session to find reci-
pients for the message.
ttsession <- ttsession
Another session wants to update (e.g. fail) a mes-
sage originating in this session.
When dispatching is being traced, matching is indicated by
one of
Tt_message & Tt_pattern {
Tt_message & ptype ptid {
Tt_message & otype otid {
The pattern or signature is printed, followed by
} == match_score; [/* mismatch_reason */]
OPTIONS
-0 Turn off message tracing in session, or run command
without message tracing (i.e., with only call tracing).
-F Follow all children forked by command or subsequently
started in session by ttsession. Normally, only the
indicated command or ttsession instance is traced.
When -F is specified, the process id is included with
each line of trace output to indicate which process
generated it.
-C Do not trace client calls into the ToolTalk API.
Default is to trace them.
-a Print all attributes, arguments, and context slots of
traced messages. The default is to use only a single
line when printing a message on the trace output.
-e script
Take script as a tttrace setting. See tttracefile(4).
-f scriptfile
File to read tttrace settings from. See tttrace-
file(4). -f - causes tttrace to read standard input
until EOF, which may prevent command from using stan-
dard input.
-o outfile
Unix System LaboratLastschange: 19 January 1994 2
tttrace(1) USER COMMANDS tttrace(1)
File to be used for the trace output.
For session tracing, output goes to standard output of
tttrace.
For client tracing, output goes by default to standard
error of tttrace. For client tracing, -o - causes
trace output to go to standard output of tttrace.
If the server for session is running on a remote host
and either
o outfile is not mounted on that host, or
o the -o option is omitted,
then tttrace will fail.
-S session
Session to trace. Defaults to the default session --
the session that tt_open() would contact.
command
The ToolTalk client command to invoke and trace.
EXAMPLES
Here we trace a client that registers a pattern and sends a
notice that matches it:
% tttrace -a myclientprogram
tt_open() = 0x51708=="7.jOHHM X 129.144.153.55 0" (TT_OK)
tt_fd() = 11 (TT_OK)
tt_pattern_create() = 0x50318 (TT_OK)
tt_pattern_category_set(0x50318, TT_OBSERVE) = 0 (TT_OK)
tt_pattern_scope_add(0x50318, TT_SESSION) = 0 (TT_OK)
tt_pattern_op_add(0x50318, 0x2f308=="Hello World") = 0 (TT_OK)
tt_default_session() = 0x519e0=="X 129.144.153.55 0" (TT_OK)
tt_pattern_session_add(0x50318, 0x519e0=="X 129.144.153.55 0") = 0 (TT_OK)
tt_pattern_register(0x50318) = 0 (TT_OK)
tt_message_create() = 0x51af0 (TT_OK)
tt_message_class_set(0x51af0, TT_NOTICE) = 0 (TT_OK)
tt_message_address_set(0x51af0, TT_PROCEDURE) = 0 (TT_OK)
tt_message_scope_set(0x51af0, TT_SESSION) = 0 (TT_OK)
tt_message_op_set(0x51af0, 0x2f308=="Hello World") = 0 (TT_OK)
tt_message_send(0x51af0) ...
TT_CREATED => TT_SENT:
TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
= 0 (TT_OK)
tt_message_receive() ...
Tt_message => procid <7.jOHHM X 129.144.153.55 0>
Unix System LaboratLastschange: 19 January 1994 3
tttrace(1) USER COMMANDS tttrace(1)
TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
pattern: 0:7.jOHHM X 129.144.153.55 0
= 0x51af0 (TT_OK)
ttsession's view of this traffic can be seen as follows.
Note that the first message traced will almost always be
ttsession's reply to the request sent it by tttrace.
% tttrace -a
tt_message_reply:
TT_SENT => TT_HANDLED:
TT_HANDLED TT_PROCEDURE TT_REQUEST (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 2.jOHHM X 129.144.153.55 0
op: Session_Trace
args:
TT_IN string: "> /tmp/traceAAAa002oL; version 1; states"[...]
session: X 129.144.153.55 0
sender: 2.jOHHM X 129.144.153.55 0
pattern: 0:X 129.144.153.55 0
handler: 0.jOHHM X 129.144.153.55 0
Tt_message => procid <2.jOHHM X 129.144.153.55 0>
tt_message_send:
TT_CREATED TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
TT_CREATED => TT_SENT:
TT_SENT TT_PROCEDURE TT_NOTICE (TT_DISCARD in TT_SESSION): 0 == TT_OK
id: 0 7.jOHHM X 129.144.153.55 0
op: Hello World
session: X 129.144.153.55 0
sender: 7.jOHHM X 129.144.153.55 0
Tt_message & Tt_pattern {
id: 0:7.jOHHM X 129.144.153.55 0
category: TT_OBSERVE
scopes: TT_SESSION
sessions: X 129.144.153.55 0
ops: Hello World
} == 3;
Tt_message => procid <7.jOHHM X 129.144.153.55 0>
To trace message flow in a specific, non-default session,
% tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"
Unix System LaboratLastschange: 19 January 1994 4
tttrace(1) USER COMMANDS tttrace(1)
ENVIRONMENT
tttrace is implemented purely as a ToolTalk client, using
the message interface to ttsession and the following
environmental hook into libtt.
TT_TRACE_SCRIPT
If set, tells libtt to turn on client-side tracing as
specified in the trace script. If the first character
of of the value is '.' or '/', the value is taken to be
the pathname of file containing the trace script to
use. Otherwise, the value is taken to be an inline
trace script.
FILES
$TMPDIR/tttrace.nnn A named pipe (see mkfifo(3C)) in $TMPDIR
(see tempnam(3S)) from which trace out-
put for session is read when the -o
option is ommitted.
WARNINGS
Since (with the -F option) tracing can follow clients to
remote hosts if the environment is properly propagated, it
is possible for different processes in the same trace output
to be labeled with the same process id.
SEE ALSO
ttsession(1), tttracefile(4), the Session_Trace() ToolTalk
request
DIAGNOSTICS
If command is run, then tttrace will exit with the exit
status of command. Otherwise, exit codes are as follows:
0 Normal termination. Any session tracing turned on by
this invocation of tttrace has now been turned off.
1 Usage. tttrace was given invalid command line options.
2 Failure. tttrace encountered an error while trying to
do its job. An error message has been emitted on stan-
dard error.
3 Runaway session tracing. tttrace could not terminate
tracing in session before exiting.
4 Remote session. ttsession is remote, and outfile (if
given) is not visible there. Choose a visible file, or
run tttrace on that remote host.
5 Old session. The ttsession for session does not sup-
port the Session_Trace() request. Run kill -USR1 on it
to turn on old-style tracing.
NOTES
For security purposes, client-side tracing is disabled
inside a client when its effective uid or gid is different
from its real uid or gid and the real uid is not the super-
user.
Unix System LaboratLastschange: 19 January 1994 5
See also tttrace(1)
Man(1) output converted with
man2html