489 lines
16 KiB
Plaintext
489 lines
16 KiB
Plaintext
<!-- $XConsortium: tttrace.sgm /main/11 1996/10/30 16:33:07 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
|
|
<RefEntry Id="CDEMX.MAN38.rsml.1" Remap="">
|
|
<RefMeta>
|
|
<RefEntryTitle>tttrace</RefEntryTitle>
|
|
<ManVolNum>user cmd</ManVolNum>
|
|
</RefMeta>
|
|
<RefNameDiv>
|
|
<RefName><Command>tttrace</Command></RefName>
|
|
<RefPurpose>trace ToolTalk calls and messages
|
|
</RefPurpose>
|
|
</RefNameDiv>
|
|
<!-- $XConsortium: tttrace.sgm /main/11 1996/10/30 16:33:07 rws $-->
|
|
<!-- (c) Copyright 1993, 1994 Sun Microsystems, Inc.-->
|
|
<!-- (c) Copyright 1993, 1994 Hewlett-Packard Company-->
|
|
<!-- (c) Copyright 1993, 1994 International Business Machines Corp.-->
|
|
<!-- (c) Copyright 1993, 1994 Novell, Inc.-->
|
|
<RefSynopsisDiv>
|
|
<CmdSynopsis>
|
|
<Command>tttrace</Command>
|
|
<Arg Choice="opt">-0FCa</Arg>
|
|
<Arg Choice="opt">-o<Replaceable>outfile</Replaceable></Arg>
|
|
<Group>
|
|
<Arg>-S<Replaceable>session</Replaceable></Arg>
|
|
<Arg><Replaceable>command</Replaceable></Arg>
|
|
</Group>
|
|
</CmdSynopsis>
|
|
<CmdSynopsis>
|
|
<Command>tttrace</Command>
|
|
<Group>
|
|
<Arg>-e<Replaceable>script</Replaceable></Arg>
|
|
<Arg>-f<Replaceable>scriptfile</Replaceable></Arg>
|
|
</Group>
|
|
<Group>
|
|
<Arg>-S<Replaceable>session</Replaceable></Arg>
|
|
<Arg><Replaceable>command</Replaceable></Arg>
|
|
</Group>
|
|
</CmdSynopsis>
|
|
</RefSynopsisDiv>
|
|
<RefSect1>
|
|
<Title>DESCRIPTION</Title>
|
|
<Para><Command>tttrace</Command> traces message traffic through the server for the indicated ToolTalk
|
|
<Emphasis>session</Emphasis>, or runs
|
|
<Symbol Role="Variable">command</Symbol> with ToolTalk client tracing turned on. If neither
|
|
<Emphasis>session</Emphasis> nor
|
|
<Symbol Role="Variable">command</Symbol> is given, the default session is traced. By default, tracing
|
|
terminates when
|
|
<Command>tttrace</Command> exits.
|
|
</Para>
|
|
<Para>Tracing of ToolTalk functions looks like this:
|
|
[<Emphasis>pid</Emphasis>] <Symbol Role="Variable">function_name</Symbol>(<Symbol Role="Variable">params</Symbol>) = <Emphasis>return_value</Emphasis> (<StructName Role="typedef">Tt_status</StructName>)
|
|
</Para>
|
|
<Para>With the
|
|
<Literal>-a</Literal> option, message attributes are printed after a one-line summary
|
|
of the message:
|
|
<Emphasis>Tt_state Tt_paradigm Tt_class</Emphasis> (<StructName Role="typedef">Tt_disposition</StructName> in <StructName Role="typedef">Tt_scope</StructName>): <Symbol Role="Variable">status</Symbol> == <StructName Role="typedef">Tt_status</StructName>
|
|
</Para>
|
|
<Para>State changes are indicated by:
|
|
<Emphasis>old_state</Emphasis> => <Emphasis>new_state</Emphasis>.
|
|
</Para>
|
|
<Para>Deliveries are indicated by:
|
|
Tt_message => procid <<Emphasis>recipient_procid</Emphasis>>
|
|
</Para>
|
|
<Para>When dispatching is being traced, the reason for each dispatch
|
|
is one of:
|
|
</Para>
|
|
<Para><Symbol>tt_message_send</Symbol>()</Para>
|
|
<Para><Symbol>tt_message_reject</Symbol>()</Para>
|
|
<Para><Symbol>tt_message_fail</Symbol>()</Para>
|
|
<Para><Symbol>tt_message_reply</Symbol>()</Para>
|
|
<Para><Symbol>tt_session_join</Symbol>()</Para>
|
|
<Para><Symbol>tt_file_join</Symbol>()</Para>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>tt_message_reply ()</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>A client called the indicated function.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>tt_message_send_on_exit ()</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para><Command>ttsession</Command> is dispatching on_exit messages for a client that
|
|
disconnected before calling
|
|
<Symbol>tt_close</Symbol>().</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>tt_message_accept ()</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para><Command>ttsession</Command> is dispatching messages that had been blocked while
|
|
a ptype was being started. The started client has now called
|
|
either
|
|
<Symbol>tt_message_accept</Symbol>() or
|
|
<Symbol>tt_message_reply</Symbol>() to indicate that the ptype should be unblocked.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_ERR_PTYPE_START</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>A ptype instance was started to receive the message, but the
|
|
start command exited before it connected to
|
|
<Command>ttsession</Command>.</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_ERR_PROCID</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para><Command>ttsession</Command> lost its connection to the client that was working on this request.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>ttsession -> ttsession</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Another session wants this session to find recipients for the message.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>ttsession <- ttsession</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Another session wants to update (e.g. fail) a message originating in this
|
|
session.
|
|
</Para>
|
|
<Para>When dispatching is being traced, matching is indicated by one of
|
|
Tt_message & Tt_pattern {
|
|
Tt_message & ptype <Emphasis>ptid</Emphasis> {
|
|
Tt_message & otype <Emphasis>otid</Emphasis> {
|
|
</Para>
|
|
<Para>The pattern or signature is printed, followed by
|
|
} == <Emphasis>match_score</Emphasis>; [/* <Emphasis>mismatch_reason</Emphasis> */]
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>OPTIONS</Title>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>-0</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Turn off message tracing in
|
|
<Emphasis>session</Emphasis>, or run
|
|
<Symbol Role="Variable">command</Symbol> without message tracing (i.e., with only call tracing).
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-F</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Follow all children forked by
|
|
<Symbol Role="Variable">command</Symbol> or subsequently started in
|
|
<Emphasis>session</Emphasis> by
|
|
<Command>ttsession</Command>. Normally, only the indicated
|
|
<Symbol Role="Variable">command</Symbol> or
|
|
<Command>ttsession</Command> instance is traced. When
|
|
<Literal>-F</Literal> is specified, the process id is included with each line of trace
|
|
output to indicate which process generated it.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-C</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Do not trace client calls into the ToolTalk API. Default is
|
|
to trace them.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-a</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>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.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-e script</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Take
|
|
<Emphasis>script</Emphasis> as a
|
|
<Command>tttrace</Command> setting. See
|
|
&cdeman.tttracefile;.</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-f scriptfile</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>File to read
|
|
<Command>tttrace</Command> settings from. See
|
|
&cdeman.tttracefile;. <Literal>-f</Literal> <Literal>-</Literal> causes
|
|
<Command>tttrace</Command> to read standard input until EOF, which may prevent
|
|
<Symbol Role="Variable">command</Symbol> from using standard input.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-o outfile</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>File to be used for the trace output.
|
|
</Para>
|
|
<Para>For session tracing, output goes to standard output of
|
|
<Command>tttrace</Command>.</Para>
|
|
<Para>For client tracing, output goes by default to standard error of
|
|
<Command>tttrace</Command>. For client tracing,
|
|
<Literal>-o</Literal> <Literal>-</Literal> causes trace output to go to standard output of
|
|
<Command>tttrace</Command>.</Para>
|
|
<Para>If the
|
|
server for
|
|
<Emphasis>session</Emphasis> is running on a remote host and either
|
|
</Para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<Para><Emphasis>outfile</Emphasis> is not mounted on that host, or
|
|
</Para>
|
|
</listitem>
|
|
<listitem>
|
|
<Para>the <Literal>-o</Literal> option is omitted,
|
|
</Para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<Para>then
|
|
<Command>tttrace</Command> will fail.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>-S session</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Session to trace. Defaults to the
|
|
<Symbol Role="Variable">default</Symbol> <Emphasis>session</Emphasis> -- the session that <ComputerOutput>tt_open()</ComputerOutput> would contact.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>command</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>The ToolTalk client command to invoke and trace.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>EXAMPLES</Title>
|
|
<Para>Here we trace a client that registers a pattern and sends a notice
|
|
that matches it:
|
|
</Para>
|
|
<Screen>% tttrace -a <Emphasis>myclientprogram</Emphasis>
|
|
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)
|
|
</Screen>
|
|
<Para><Command>ttsession</Command>'s view of this traffic can be seen as follows. Note that the first message
|
|
traced will almost always be
|
|
<Command>ttsession</Command>'s reply to the request sent it by
|
|
<Command>tttrace</Command>.</Para>
|
|
<Screen>% <Command>tttrace</Command> -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>
|
|
</Screen>
|
|
<Para>To trace message flow in a specific, non-default session,
|
|
</Para>
|
|
<Screen>% tttrace -S "01 15303 1342177284 1 0 13691 129.144.153.55 2"
|
|
</Screen>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>ENVIRONMENT</Title>
|
|
<Para><Command>tttrace</Command> is implemented purely as a ToolTalk client, using the message
|
|
interface to
|
|
<Command>ttsession</Command> and the following environmental hook into libtt.
|
|
</Para>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>TT_TRACE_SCRIPT</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>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.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>FILES</Title>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>$TMPDIR/tttrace.nnn</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>A
|
|
<Emphasis>named</Emphasis> <Emphasis>pipe</Emphasis> (see
|
|
<Filename MoreInfo="RefEntry">mkfifo</Filename>(3C)) in <Symbol>$TMPDIR</Symbol> (see
|
|
<Filename MoreInfo="RefEntry">tempnam</Filename>(3S)) from which trace output for
|
|
<Emphasis>session</Emphasis> is read when the
|
|
<Literal>-o</Literal> option is omitted.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>WARNINGS</Title>
|
|
<Para>Since (with the
|
|
<Literal>-F</Literal> 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.
|
|
</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>SEE</Title>
|
|
<Para>&cdeman.ttsession;, &cdeman.tttracefile;, the
|
|
<Literal>Session_Trace</Literal>() ToolTalk request
|
|
</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>DIAGNOSTICS</Title>
|
|
<Para>If
|
|
<Symbol Role="Variable">command</Symbol> is run, then
|
|
<Command>tttrace</Command> will exit with the exit status of
|
|
<Symbol Role="Variable">command</Symbol>. Otherwise, exit codes are as follows:
|
|
</Para>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>0</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Normal termination. Any
|
|
<Emphasis>session</Emphasis> tracing turned on by this invocation of
|
|
<Command>tttrace</Command> has now been turned off.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>1</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Usage.
|
|
<Command>tttrace</Command> was given invalid command line options.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>2</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Failure.
|
|
<Command>tttrace</Command> encountered an error while trying to do its job. An error
|
|
message has been emitted on standard error.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>3</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Runaway
|
|
<Emphasis>session</Emphasis> tracing.
|
|
<Command>tttrace</Command> could not terminate tracing in
|
|
<Emphasis>session</Emphasis> before exiting.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>4</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Remote
|
|
<Emphasis>session</Emphasis>. <Command>ttsession</Command> is remote, and
|
|
<Emphasis>outfile</Emphasis> (if given) is not visible there. Choose a visible file,
|
|
or run
|
|
<Command>tttrace</Command> on that remote host.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>5</Term>
|
|
<ListItem>
|
|
<!-- ex-TP-->
|
|
<Para>Old
|
|
<Emphasis>session</Emphasis>. The
|
|
<Command>ttsession</Command> for
|
|
<Emphasis>session</Emphasis> does not support the <ComputerOutput>Session_Trace()</ComputerOutput> request. Run
|
|
<Literal>kill</Literal> <Literal>-USR1</Literal> on it to turn on old-style tracing.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>NOTES</Title>
|
|
<Para>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.
|
|
</Para>
|
|
</RefSect1>
|
|
</RefEntry>
|
|
<!--fickle 1.12 mancsf-to-docbook 1.3 08/21/95 21:30:04-->
|