The ToolTalk ttsession trace ttsession trace shows how ToolTalk pattern matches and delivers every message ttsession sees. ToolTalk tracing for this release also Displays a single client's interactions with ToolTalk. This feature allows implementors to focus on only one client. Filters the ttsession trace by, for example, message type, sender, or receiver. A command new for this release, tttrace ToolTalk commands tttrace tttrace, is the primary way to access ToolTalk tracing. This command is similar in purpose and command‐line interface to the truss command truss command. It enables you to control the three kinds of ToolTalk tracing. The tttrace command tttrace command has two fundamental modes: server mode server mode and client mode client mode. In server mode, tttrace directs the indicated session to trace by sending it a Session_Trace request. In client mode, tttrace sets an environment variable and executes the ToolTalk client command given on the command line. The environment variable in the executed client instructs libtt libtt whether, and how, to trace client messaging and client API calls. tttrace is not downward compatible with older servers or with clients using older versions of libtt. While tttrace will detect and diagnose older servers, it fails silently on clients using older versions of libtt. One way to control libtt's tracing behavior is to set the environment variables $DT_TT_TRACE_SCRIPT environment variable $ $DT_TT_TRACE_SCRIPT TT_TRACE_SCRIPT. libtt's tracing fails gracefully if the variable's value is corrupt or inconsistent. The tt_trace_control call tt_trace_control call sets or clears an internal flag to control all client‐side tracing. You can use this call to trace suspect areas in your code. The format of this call is: int tt_trace_control(int option) where option 0 to turn traciing off; 1 to turn tracing on; and -1 to toggle tracing on and off. When tracing is on, the extent of tracing is controlled by the tttrace command TT_TRACE_SCRIPT variable or tracefile. This call returns the previous setting of the trace flag. The Session_Trace request Session_Trace request is a ToolTalk request that ttsession registers to handle itself; that is, ttsession is the handler for the Session_Trace request. This request can be sent by any ToolTalk client, and, although not recommended, other ToolTalk clients can register to handle this request. (Note: This method will cause tracing to not work.) The syntax for this request is: [file] Session_Trace( in boolean on, in boolean follow [in attribute toPrint |in state toTrace |in op toTrace |in handler_ptype toTrace |in sender_ptype toTrace][...] ); The Session_Trace request turns message tracing in the scoped-to session on or off. If tracing is on and the file attribute of the request is set, subsequent trace output is appended to the file named by the attribute. If tracing is on and the file attribute is not set, tracing continues to the current trace. By default, daemon mode causes the output to go to the console of the host on which ttsession is running; job-control mode causes the output to go to ttsession's standard error. describes the required and optional arguments for this request. Argument Description boolean on Required Turn tracing on or off. If no toTrace arguments are included and on is true, the previous trace settings are restored. boolean follow Required Turn on client-side tracing for Invoked clients. attribute toPrint Optional Print attribute(s) for each message traced. Valid attributes are:• none–print only a one-line description of traced messages (default)• all–print all attributes of traced messages state toTrace Optional State(s) through which to trace messages. In addition to the Tt_states defined in tt_c.h, valid states are:• edge–messages entering initial (TT_SENT) and final (TT_HANDLED, TT_FAILED) states.• deliver–all state changes and all client deliveries.• dispatch–deliver + all patterns considered for matching. (default) op toTracesender_ptype toTracehandler_ptype toTrace OptionalOptionalOptional Trace messages that have toTrace as a value for the indicated message attribute.• Any number of toTrace arguments may be included in the request.• toTrace may include sh wildcard characters.• If no toTrace argument is included for a given message attribute, no value of that attribute excludes a message from tracing. The current session tracing behavior changes only if this request is not failed. On failure, the tt_message_status of the reply is set to one of the errors described in . Error Description TT_ERR_NO_MATCH errors returned TT_ERR_NO_MATCH TT_ERR_NO_MATCH No handler could be found for the request. TT_ERR_APPFIRST + EACCES errors returned TT_ERR_APPFIRST + EACCES TT_ERR_APPFIRST + EACCES ttsession does not have permission to open or create the trace file. TT_ERR_APPFIRST + EISDIR errors returned TT_ERR_APPFIRST + EISDIR TT_ERR_APPFIRST + EISDIR The trace file is a directory. TT_ERR_APPFIRST + ENOSPC errors returned TT_ERR_APPFIRST + ENOSPC TT_ERR_APPFIRST + ENOSPC There is not enough space in the target file system to create the trace file. TT_ERR_APPFIRST + EEXIST errors returned TT_ERR_APPFIRST + EEXIST TT_ERR_APPFIRST + EEXIST Tracing is already occurring on another file. ttsession resets the file attribute of the reply to name the existing trace file. To trace to a different file, first turn off tracing to the current trace file. The tttrace function ToolTalk functions tttrace tttrace function traces message traffic through the server for the indicated ToolTalk session, or runs a command with ToolTalk client tracing turned on. If neither the session nor the command is given, the default session is traced. By default, tracing terminates when tttrace exits. The syntax for this function is: tttrace [-0FCa] [-o outfile ] [-S session | command] tttrace [-e script | -f scriptfile ] [-S session | command] describes the tttrace options. Option Description -0 Turns off message tracing in session, or runs the specified command without message tracing (that is, with only call tracing). -F Follows all children forked by the indicated command, or subsequently started in session by ttsession. Normally, only the indicated command or a ttsession instance is traced. When the -F option 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. The default is to trace the calls. -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. -o outfile The file to be used for the trace output. For session tracing, output goes to standard output of tttrace. -S session The session to trace. Defaults to the default session; that is, the session that tt_open tt_open would contact. command The ToolTalk client command to invoke and trace. -e script The script to be used as a ttrace setting. -f scriptfile The file from which to read the tttrace settings. tttrace is implemented purely as a ToolTalk client, using the message interface to ttsession and the TT_TRACE_SCRIPT environment variable TT_TRACE_SCRIPT environment variable. If this variable is set, it 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 path name of file containing the trace script to use; otherwise, the value is taken to be an inline trace script. The following is an example of how a traced ToolTalk function looks. [pid] function_name(params) = return_value (Tt_status) The -a option prints message attributes after a one-line summary of the message, as follows: Tt_state Tt_paradigm Tt_class (Tt_disposition in Tt_scope): status == Tt_status State changes are indicated by the following format: old_state => new_state. Deliveries are indicated by the following indicated: Tt_message => procid recipient_procid dexplains the messages you may receive during a dispatch trace. Message Explanation tt_message_send The message to send. tt_message_reject The message was rejected. tt_message_fail The message failed. tt_message_reply The reply to a message. tt_session_join The session to join. tt_file_join The file to 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 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 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 recipients for the message. ttsession <- ttsession Another session wants to update (for example, 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 { formats: The pattern or signature is printed, followed by: } == match_score; [/* mismatch_reason */] This sections contains examples of how to use the tttrace function. To register a pattern and send a notice that matches the pattern, type: % tttrace -a myclientprogram shows the results. 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) To see ttsession's view of the message flow, type: % tttrace -a ttsession's view 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> of mylientprogram's message flow is shown in . The first message traced will almost always be ttsession's reply to the request sent to it by tttrace. To trace the message flow in a specific, non-default session, type: % tttrace -S “01 15303 1342177284 1 0 13691 129.144.153.55 2“ where “01 15303 1342177284 1 0 13691 129.144.153.55 2“ is the specific, non-default session to be traced. A tttrace script contains settings that control ToolTalk calls and messages. A tttrace script consists of commands separated by semicolons or newlines. If conflicting values are given for a setting, the last value is the one used. describes these commands. Command Description version n The version of the tttracefile command syntax used. The current version is 1. follow [off | on] Sets whether to follow all children forked by the traced client or subsequently started in the traced session. Default is off. [> | >>] outfile File to be used for the trace output. By default, trace output goes to standard error. Normal shell interpretation of > and >> applies. functions [all | none | func...] ToolTalk API functions to trace. func may include shell wildcard characters. Default is all. attributes [all | none] none (default) means use only a single line when printing a message on the trace output; all means print all attributes, arguments, and context slots of traced messages. states [none | edge | deliver | dispatch | Tt_state]... State(s) through which to trace messages. In addition to the Tt_states defined in tt_c.h, valid states are:• none – disable all message tracing• edge – messages entering initial (TT_SENT) and final (TT_HANDLED, TT_FAILED) states.• deliver – all state changes and all client deliveries.• dispatch – deliver plus all patterns considered for matching (default). ops toTrace...sender_ptypes toTrace...handler_ptypes toTrace... Trace messages that have toTrace as a value for the indicated message attribute. toTrace may include shell wildcard characters. If no toTrace argument is included for a given message attribute, then no value of that attribute excludes a message from tracing.