xtil(CP) 6 January 1993 xtil(CP) Name xtil - XTI library trace control Syntax xtil [-cdmv] file ... Description The trace mechanism of the XTI library is activated and controlled via the environment variable XTITRACE. The trace entries of a process are collected in compressed, binary format in a dynamically created buffer and are periodically written to temporary files. These files are edited in a separate step using xtil. Controlling the trace mechanism - XTITRACE Every initial XTI call issued by a process evaluates the environment variable XTITRACE and, when appropriate, activates the trace mechanism. Following activation of the trace mechanism, the temporary file XTIF<pid> with the process ID <pid> is opened, if it has not already been opened. The files are granted the access permissions rw------- (0600). The files are located under the login name of the process. Storage is then dynamically reserved for buffering the trace entries. Storage and files are reserved for the life of the process. The options specified in XTITRACE control the trace mechanism. Options -s and -S determine the extent of logging. Options -p and -r control buffering and cyclical overwriting of the file. The syntax for setting the XTITRACE environment variable is: XTITRACE="{-sS} [-p fac] [-r wrap]" export XTITRACE The options to XTITRACE are: -s The command names the values of the arguments, and the return values of the commands are logged. In the event of error, terrno, errno, and the error position errpos in the library are output. -S The same log is kept as for option -s. In addition, for argu- ments which involve pointers, the data structures addressed by the pointers are logged. Only one of the options -s and -S may be specified. To activate the trace mechanism one of these two values must be specified. -p fac The decimal digit fac determines the buffering factor. The buffer size is fac * BUFSIZE, with BUFSIZE as defined in stdio.h. If 0 is specified for fac, every trace entry is writ- ten immediately to the file (unbuffered). Any value specified for fac exceeding 8 is automatically reduced to 8. If the -p option is not specified, fac defaults to 1. -r wrap The decimal number wrap specifies that logging is to be directed to the second temporary file XTIS<pid> after wrap * BUFSIZE (with BUFSIZE as defined in stdio.h). The second file XTIS<pid> is handled by the trace mechanism in the same way as XTIF<pid>. After every wrap * BUFSIZE bytes, the trace mechanism switches between XTIF<pid> and XTIS<pid>. When this is done the old con- tents of the second file are lost. If -r is not specified, wrap defaults to 512. Editing the trace information - xtil xtil reads the entries generated by the trace mechanism from the tem- porary file file, processes them in accordance with the specified options and outputs the results on standard output. The options specify which trace entries from file are to be edited. More than one of the values may be specified per xtil call. If no option is specified, -cdm is assumed. -c Editing is performed for the XTI calls for attaching and detaching the TS application, and for connection setup and disconnection. These are calls taccept(), tbind(), tclose(), tconnect(), tlisten(), topen(), trcvconnect(), trcvdis(), trcvrel(), tsnddis(), tsndrel(), and tunbind(). -d Editing is performed for the XTI calls for data exchange. These are calls trcv(), trcvudata(), trcvuderr(), tsnd(), and tsndudata(). -m Editing is performed for the other XTI calls that are not edited when options -c and -d are specified. These are calls talloc(), terror(), tfree(), tgetaddr(), tgetinfo(), tgetloc(), tgetname(), tgetstate(), tlook(), toptmgmt(), and tsync(). -v Detailed editing is performed for the XTI calls, their argu- ments, and the options. For arguments transferred as pointers, the addressed data structures are also output. The extent of editing of the data depends on the options specified in XTI- TRACE. If only -v is specified, this is the same as specifying -cdmv. file ... The name of one or more files with binary trace entries to be edited. Output format for XTI library trace function The trace information edited by xtil always starts with two header lines, for example: XTI TRACE (V1.0) Fri Aug 12 15:13:34 1990 OPTIONS 'cmdv' , TRACE FILE 'XTIFa00963' The two header lines are output once at the start of the output of the trace information. They contain: - the version of the XTI command library, - the date and time tracing was started, - the editing options selected, and - the name of the edited trace file. Trace information for the individual XTI calls is output over several lines, the different lines having different formats. The number of lines depends on the options specified for XTITRACE and xtil. The first line is always output. It contains the following information: - A timestamp at the start of the first line. - The logged XTI call (txxxxx). - The arguments and their values (enclosed in parentheses), in the order required by XTI. The arguments are shown in decimal form (%d), hexa- decimal form (0x%x), or symbolic form (%s). The hexadecimal form is preceded by ``0x''. When interpreting the logged values, note the following: - Arguments involving addresses are shown in the form (0x%x). - For arguments of type integer (*.len, *.maxlen), the corresponding values are shown in form 0x%x, %d, or %s, separated by a space from the argument name. For commands, the processing of which depends on the file mode, it is also stated whether the access was blocking (specification: BLOCK) or non-blocking (specification: NBLOCK). The following lines are only output when option -v is specified for xtil and the trace facility has collected suitable information (option -S for XTITRACE). In these lines, the arguments involving pointers also have the data structures they address displayed. The values of the structure com- ponents are edited in hexadecimal and in plain text. The naming of argu- ments and structure components is in compliance with the X/Open Portabil- ity Guide 3. The following applies to marking structure components: > The TS application must assign the component a legal value. < The XTI functions assign the component a legal value if the command runs without error. - The value of the component has no significance for the logged XTI call. --- If ``---'' is specified instead of the value of a component, the component does not contain a legal value. The last line of the output for an XTI call contains the return value. In the event of error, terrno (if applicable), errno, and information on the error location in the library (errpos) are output. Example The example below shows the detailed log for an XTI call. 08:24:16 t_bind (fd 5, req 0x8054ac8, ret 0x0) req: addr.maxlen(-) addr.len(>) addr.buf(>) --- 24 0x8054d48 0 01001800 0e000000 00000004 04003234 | 24| 10 39370000 00000000 |97 | qlen (>) 10 qlen (<) 0 return: 0 Files XTIF<pid> Files with compressed trace entries. XTIS<pid> Diagnostics If the command terminates successfully, the exit status is zero, other- wise it is non-zero.