 |
Index for
Section 1 |
|
 |
Alphabetical
listing for T |
|
 |
Bottom of
page |
|
tttrace(1)
CDE
NAME
tttrace - trace ToolTalk calls and messages
SYNOPSIS
tttrace [-0FCa] [-o outfile] [-S session | command]
tttrace [-e script | -f scriptfile] [-S session | command]
OPTIONS
-0 Turns off message tracing in session, or run command without message
tracing (i.e., with only call tracing).
-F Follows all children forked by command or subsequently started in
session by ttsession. Usually, 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 Does not trace client calls into the ToolTalk API. Default is to trace
them.
-a Prints 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
Takes script as a tttrace setting. See tttracefile(4).
-f scriptfile
File where tttrace settings are located. See tttracefile(4). A value
of '-' means to use standard input to read settings. -f - causes
tttrace to read standard input until EOF, which may prevent command
from using standard input.
-o outfile
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
outfile is not mounted on that host, or the -o option is omitted, then
tttrace will fail.
-S session
Session to trace. Defaults to the default session -- the session that
CWtt_open() would contact.
command
The ToolTalk client command to invoke and trace.
DESCRIPTION
The tttrace command 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_session_join()
tt_file_join()
tt_message_reply()
A client called the indicated function.
tt_message_send_on_exit()
The ttsession instance is dispatching on_exit messages for a client
that disconnected before calling tt_close().
tt_message_accept()
The ttsession instance 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 indicate that the
ptype should be unblocked.
TT_ERR_PTYPE_START
A ptype instance was started to receive the message, but the start
command exited before it connected to he ttsession instance.
TT_ERR_PROCID
The ttsession instance lost its connection to the client that was
working on this request.
ttsession -> ttsession
Another session wants this session to find recipients for the message.
ttsession <- ttsession
Another session wants to update (fail) a message originating in this
session.
When dispatching is being traced, matching is indicated by one of the
following:
Tt_message & Tt_pattern {
Tt_message & ptype ptid {
Tt_message & otype otid {
The pattern or signature is printed, followed by:
} == match_score; [/* mismatch_reason */]
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 superuser.
ENVIRONMENT
The tttrace command 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 the value is '.' or '/', the
value is taken to be the pathname of the file containing the trace
script to use. Otherwise, the value is taken to be an inline trace
script.
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.
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. The tttrace command was given invalid command line options.
2 Failure. The tttrace command encountered an error while trying to do
its job. An error message has been written to standard error.
3 Runaway session tracing. The tttrace command 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 support the
CWSession_Trace() request. Run kill -USR1 on it to turn on old-style
tracing.
EXAMPLES
1. 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>
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)
2. The ttsession session's view of this traffic can be seen as follows.
The first message traced almost always will 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>
3. To trace message flow in a specific, non-default session:
% tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"
FILES
$TMPDIR/tttrace.nnn
A named pipe (see mkfifo(1)) in $TMPDIR (see tempnam(3)) from which
trace output for session is read when the -o option is omitted.
SEE ALSO
Commands: ttsession(1)
Files: tttracefile(4)
The Session_Trace() ToolTalk request
|
Index for
Section 1 |
|
|
Alphabetical
listing for T |
|
 |
Top of
page |
|