packages icon



 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



 NAME
      tusc - trace unix system calls

 SYNOPSIS
      tusc [options] command [args ...] | pid [pid ...]

      truss [options ] command | -p pid ...

 DESCRIPTION
      Tusc traces the system calls a process invokes and the signals it
      receives. It displays arguments in a symbolic way, shows the first
      bytes of read and write buffers as well as signal information when
      available. Tusc can attach to live processes by providing PIDs
      (process IDs) as argument(s).

      If desired, tusc can be invoked as truss, by linking one binary to the
      other, in order to provide reasonable compatibility with the
      UnixWare/Solaris tracing tool (see "TRUSS COMPATIBILITY" below).

      When invoked as tusc, the options are:

      -a      Print exec arguments. If execv(2) syscall is being traced,
              print all exec arguments and their addresses.

      -A      Append to output file. This option has no effect if an output
              file has not been specified using the -o option.

      -B      Show branch events, on IPF (this option is not supported on
              PA-RISC).  To obtain meaningful data, the -i should be used
              with this option.

      -b bytes
              Set max data size for -r and -w options. By default, when
              using these options, the whole read/write buffers are dumped.
              This option causes a maximum bytes number of bytes to be
              displayed.

      -c      Count syscalls and signals. If a single -c is present, tusc
              will only report the number of system calls executed by the
              process(es), the number of errors, if any, the accumulated CPU
              time for each syscall, and the number of signals.  If more
              than one -c is present, tusc will behave as if this option was
              not used (i.e. display its normal output) but will report
              these statistics upon completion.  If more than two -c's are
              present, the CPU time for each syscall instance is also
              reported, in seconds, between angle brackets at the beginning
              of each line.

      -C      Is similar to -c option but provides more precision and more
              information, in particular, the low, high and average system
              call times.



                                    - 1 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      -d [+][!]fds
              Select file descriptors. This option allows the user to
              display syscalls using certain file descriptors. If the first
              character of the string is a plus sign (+), syscalls that do
              not return or whose argument list doesn't contain file
              descriptors are also displayed. For the remaining part of the
              argument string, see the ARGUMENT LISTS section below.  Note
              that, unlike with the -s option, the system call filtering is
              done by tusc, not by the kernel. See also the -r and -w
              options.

              For instance, using tusc -d8 date will only display syscalls
              using file descriptor 8 but using tusc -d+8 date will also
              display syscalls which do not involve file descriptors.

      -D      Print syscall execution time, i.e. the elapsed time between
              syscall entry and return events, in parenthesis. Note that
              this data is more accurate on 11.31 than on older versions
              because, starting with that version, the timing information is
              provided by the kernel. On older releases, particularly under
              heavy CPU loads, latency can influence these values.

      -e      Print environment variables. If execv(2) syscall is being
              traced, print all environment variables and their addresses.

      -E      Show syscall entries. Tusc doesn't require OS notification for
              system call entry. It collects all the data it needs when the
              system call returns. This option will cause tusc to stop upon
              syscall entry and produce a trace. This option is only useful
              for processes encountering invalid syscall errors as it will
              show the number of the invalid syscall.

      -f      Follow forks. Normally tusc only traces the parent side of
              fork(2)s.  With this option, it will trace all children. Note
              that debuggers or tracers (like tusc) cannot be followed since
              only one debugger is allowed to attach to a process at any
              given time.

      -F      Print feature level. Newer kernels provide a way to obtain the
              ttrace feature level. This option will return that level. See
              <sys/ttrace.h>.

      -g      Do not allow attaching to any process in tusc's session (see
              getsid(2)).  This option is only meaningful when providing
              process IDs as arguments.

      -G      Print syscall list (#define, id and number of arguments) for
              validation purposes.

      -h      Print the status of the entire process hierarchy when idle.
              Normally, unless the -i is specified, tusc reports the waiting



                                    - 2 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



              syscall for the last active process only. With this option the
              state of all processes currently traced is reported.

      -i      Don't show sleeping (interruptible) syscalls.  By default, if
              a system call takes more than 1 to 2 seconds to complete, or
              if the traced process is spinning in user mode, an indication
              of the state of the process is displayed. If this option is
              used, these traces are suppressed. See ENVIRONMENT section.

      -I n1[/n2]
              Single-step and display instructions. This option allows the
              user to single-step through the target program between all or
              some of the system calls. The output can be fed to a
              disassembler to provide more information.  The n1 argument
              specifies that single-stepping should occur after the n1'th
              syscall. The n2 argument specifies the number of syscalls
              after which single-stepping will stop (default is the
              remainder of the process).
              The PC and instructions  that are displayed (not available
              with older kernels) are obtained from the SIGTRAP siginfo and
              are the PC/instruction where the single-step originated from.
              If a single -v flag is provided, the current PC and
              instruction  will also be displayed.  If two -v flags are
              present, the register context at the time of the single-step
              is also printed.

      -k      Keep tracing after main process exits. Normally, when
              specifying a binary (not a process ID) to trace and following
              children, tusc will terminate when that process exits. This
              option forces it to wait until all children have exited. This
              is especially useful when tracing daemon processes that place
              themselves in the background by forking and exiting the
              parent. When this option is used, tusc exits with the exit
              code of the process that was last traced.

      -l      Print all lwpids. This option is most useful when tracing
              multi-threaded processes.

      -n      Print process names. This option is most useful when tracing a
              large number of processes.

      -o [file|fd]
              Send trace output to given file or file descriptor.  Normally,
              tusc's output goes to standard output. This option provides a
              way to separate tusc's standard output from that of the
              process(es) it traces. If the argument is a valid number
              greater than zero, it is assumed to be a file descriptor, not
              a file name.  For instance, "tusc -o2" will cause the traces
              to go to stderr.





                                    - 3 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      -p      Print pids. By default, process IDs are not printed.

      -Q      Quiet. Most informational warnings are not printed.

      -r [!]fds
              Print read buffers for given file descriptors. If this option
              is used, all (unless the dump size is modified using the -b
              option) read data performed by the specified file
              descriptor(s) is dumped.  See the ARGUMENT LISTS section
              below.

              The data, by default, is displayed 32 byte wide using
              characters followed by a blank, if the character is printable,
              a "C" escape sequence notation or a 2 digit hexadecimal value.
              See the ENVIRONMENT section for ways to dump data in different
              formats.

              Note that the -d option has precedence: no buffer data will be
              displayed if the file descriptor has been selected out.

      -R      Show syscall restarts. This option shows system call restarts.
              It is not clear how useful it is at this point.

      -s [!]syscalls
              Select syscalls. By default, all system calls are traced. This
              option allows a user to trace a limited number of calls.  See
              the ARGUMENT LISTS section below.  The arguments can be a
              combination of numbers, full system call names or global
              expressions.

      -S [!]signals
              Select signals. By default, all signals are traced. This
              option allows tracing of a limited number of signals.  See the
              ARGUMENT LISTS section below.  The arguments can be a
              combination of numbers, full signal names or signal names
              without the SIG prefix (i.e.  SIGINT or INT both work).
              Specifying uncatchable signals has no effect.

      -t      Detach process if it enters traced mode. If this option is
              used, tusc silently checks system call entry events and
              releases the process if it is performing a
              ttrace(TT_PROC_SETTRC) or a ptrace(PT_SETTRC) syscall. If the
              call is ttrace(TT_PROC_ATTACH) or ptrace(PT_ATTACH), the
              process being attached to is also released if tusc was tracing
              it.

      -T format
              Show time stamp for each syscall and signal. If the format
              argument is an empty string or if it is the string "hires",
              the time of day in tv_sec.tv_usec format will be displayed.
              Else, format is expected to be a string containing time



                                    - 4 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



              formatting directives. For details, refer to the strftime(3C)
              man page.

      -u      User thread IDs. If this option is present, user thread IDs
              (see pthreads) are displayed.

      -v      Verbose. If this option is present, more verbose data is
              produced for some system calls. Additional -v options will
              provide more data for a subset of those syscalls (the stat,
              statfs, statvfs and pstat families). Three -v options provides
              the most verbosity at this time.

      -V      Print version. This option simply prints the current tusc
              version.

      -w [!]fds
              Print write buffers for given file descriptors. Identical to
              -r option but for write buffers.

      -x      Print raw (hex) arguments. Tusc produces symbolic output for a
              large number of system calls. This option causes all arguments
              to be displayed in hexadecimal rather than in symbolic form.
              If used with the -v option, data that are normally displayed
              in symbolic form are also displayed in hexadecimal.

      -X      Print syscall traces in an exportable format. When this option
              is used, Tusc will print the syscall traces in an format that
              will allow them to be imported by a spreadsheet: IDs, time
              stamps, syscall name, syscall argument(s) in a single
              parenthesized block and return value(s) are separated with
              tabs. Signal traces are split in 2 blocks, the first one being
              the signal received, the second the remainder of the data.
              Refer to the ENVIRONMENT section if another field separator is
              desired.  All verbose or buffer data is unchanged.

      -y      Verbose option for registers. A single -y will print the PC
              (and disassemble the instruction, on IPF), an additional -y
              will dump all registers. This option is only meaningful when
              -I is used.  For backward compatibility, the -v option has the
              same effect on register display but will also produce verbose
              system call data where available.

      -z      Do not print information about successful syscalls. Print only
              failed syscalls as well as all signals.

 ARGUMENT LISTS
      Several tusc options require a list of objects (syscalls, file
      descriptors, signals). The argument lists are in the form:

                 [!]arg1[,arg2[,...]]




                                    - 5 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      The optional leading '!', means "all but". The rest of the string is a
      list of arguments separated by commas (',') or the all keyword which,
      except for syscall names,  has the expected behavior.

      The -d option supports multiple file descriptor ranges in the form:

                 [!]low-high,[low2-high2],...

      The -s option supports a single begin-end range as argument:

                 [!]syscall-[syscall]

      where syscall can be a system call number or an exact system call
      name.  If the second value is omitted, the last system call number is
      implied.  This is mostly useful to debug newly added syscalls
      internally.

 SEE ALSO
      ttrace(2), ttrace_wait(2), strftime(3c), regcomp(3), fnmatch(3).

      A front end script, sstep, is available to provide on-the-fly symbolic
      disassembly.

 EXAMPLES
      tusc date Trace the date(1) command.

      tusc 1    Trace init(1M), if super-user.

      tusc -f -o make.trace make
                Trace make(1) and all the processes it invokes and send the
                output to the file make.trace.

      tusc -s read,write cat /etc/passwd
                Show the read and write syscalls from the command 'cat
                /etc/passwd'.

      tusc -s !sig,mmap sleep 10
                Show all system calls except mmap and those having 'sig' in
                their name.

 CAVEATS
      Tusc cannot trace a process being debugged or traced by another
      process since a process may only have one debugger at a time.

      Historically, debuggers (applications using tracing interfaces) have
      destroyed their children, or the processes they are attached to, when
      exiting, or, rather, the operating system has provided this service to
      them.  This is clearly not always a desirable behavior and tusc
      catches signals in order to detach itself from processes it may have
      attached to, before exiting. However, in the case of multiple tracers
      tracing each other and the last one attaching to a live process (for



                                    - 6 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      instance, "tusc tusc <PID>"), it is possible that the first tracer
      will exit first, taking the entire process chain with it and not
      allowing the last one to detach from the PID before exiting.
      Newer (currently unreleased) versions of the OS allow a debugger to
      specify what action should be taken upon debugger exit. Tusc uses the
      detach-on-exit option when running on OSes that provide that option.

      When tracing the crooked shell (aka C-shell, aka csh) and following
      children, on 11.0, one should ignore SIGUSR1 to avoid races between
      parent and child processes. This problem is fixed in the 11i kernel.

 NOTE
      The tusc interface and features may evolve in the future.

 TRUSS COMPATIBILITY
      If tusc is invoked as truss, it provide some level of compatibility
      with the latter:

      o The default trace output becomes stderr.

      o The default filler character is changed from dot to space.

      o The pid/lwpid display more closely resembles output from truss.

      The following truss options are supported (see truss(1) on UnixWare or
      Solaris for details):

      -a      Same as tusc's.  Compatible with truss.

      -c      Same as tusc's but only one level supported.

      -d      Compatible with truss.

      -D      Same as tusc's -ccc but without the syscall summary.

      -e      Same as tusc's.  Compatible with truss.

      -f      Same as tusc's but also turns on process ID display as it does
              with truss.

      -i      Same as tusc's.  Compatible with truss.

      -l      Same as tusc's.  Compatible with truss.

      -o      Same as tusc's.  Compatible with truss.

      -p      Compatible with truss.

      -r      Same as tusc's.  Compatible with truss.





                                    - 7 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      -s      Same as tusc's -S option.  Compatible with truss.

      -t      Same as tusc's -s option.  Compatible with truss.

      -v      Argument is ignored. -v is turned on for all syscalls.

      -w      Same as tusc's.  Compatible with truss.

      -x      Argument is ignored. -x is turned on for all syscalls.

      The following truss options are not supported: -m, -M, -T, -S, -u, -U.

 ENVIRONMENT
      Tusc aligns return values, when possible, and uses dots as filler.  If
      the TUSCFILLER variable is set, that string is used as filler instead
      if it doesn't contain tabs or non printable characters.

      Unless the -i option is used, tusc uses a 2 second alarm to report
      sleeping system calls in the process that was last continued. The
      TUSCALARM variable may be used to change the default alarm.

      Tusc has preset values to horizontally divide the output into syscall
      data and return value. The TUSCMARGIN variable may be set to specify a
      number of columns for the latter. Values greater than the number of
      columns are ignored.

      The width used to print process names, when the -n option is used, can
      be adjusted by setting the TUSCNMW variable to a positive number.

      If the -n option is used, TUSCSN can be set to true to convert
      commands' full path names into simple names.

      By default, read/write buffers contents are displayed in character
      pairs, using the following algorithm: ascii printable characters are
      printed with a space on the right, the "C" language's escape character
      constants (\0, \n, \r, etc...) are printed as such and all other
      characters are printed in hexadecimal. The TUSCBUFMODE variable alters
      this behavior.  If it is set to truss (or if the program is invoked as
      truss), the space will be to the left of the printable characters.  If
      it is set to hex, all words will be printed in hexadecimal. If it is
      set to ascii, printable characters will be printed without spaces on
      the right and non-printable characters will be shown as dots. If it is
      set to dual, hexadecimal values are printed on the left of the pipe
      sign, ascii on the right. In dual mode, output resulting from the -r
      and -w options is also boxed, the hex values are space separated and
      the columns are numbered.

      Some system calls have variable argument lists. If TUSCVARARGS is set
      to true, these syscalls will only display the arguments examined by
      the OS to avoid displaying garbage.  Currently, only open(2),
      ptrace(2) and sysfs(2) have been registered as supporting variable



                                    - 8 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      arguments.

      Tusc reports inconsistent number of arguments between what it expects
      and what the OS reports. Undeclared syscalls (reported as SC-### where
      ### is the syscall number) do not generate this warning unless
      TUSCMMAW, which stands for "mismatch argument warning", is set to all.
      Note that these warnings or any "SC-###" report indicates that tusc's
      internal syscall table should be updated.

      By default, when running in truss compatibility mode, unsupported
      options cause a warning to be printed to stderr. If TRUSSSTRICT is set
      to true, unsupported options will cause truss to exit.

      Setting the TUSCL10N variable to true will cause system error
      messages, time stamps and floating numbers to be localized on systems
      that support it.

      By default, the verbose output is center justified and aligned on the
      colon, if the LHS is wide enough, and always includes at least 2
      spaces on the left. The TUSCVWIDTH variable controls the position of
      the colon.  If that variable is set to zero, the output will be left
      justfied. The verbose data for the getdents syscall is always left
      justified, due to the nature of the output.

      The TUSCMATCH variable controls what type of pattern matching is used.
      If the value is reg, tusc evaluates regular expressions using
      regcomp(3) with the REG_ICASE and REG_NOSUB options. If the value is
      sh, tusc uses shell (see sh(1)) pattern matching. If the value is
      both, the latter is used if the former doesn't provide a match. When
      running in truss emulation mode, the variable is not evaluated and sh
      pattern matching is used.

      Unless the -x option is used, IPv6 addresses are printed using the
      double colon ('::') notation to skip contiguous zero elements (for
      instance, the IPv6 loopback would be displayed as ::1).  If this
      behavior is not desired, setting TUSCRAWIPV6 to true will cause tusc
      to print all elements.

      By default, tusc ignores failing system calls when setting high/low
      execution times (-C option).  Setting the TUSCHILOERRS variable to
      true will cause tusc to include failing syscalls.

      By default, tusc uses tabs as field separators when the -X option is
      used. The TUSCSEP can be used to specify a character string (including
      a null string) to be used instead of the tabs.

      When single-stepping on IPF, the default is to use symbolic register
      names.  If the TUSCPHYSREGNAMES variable is set to true, physical
      register names will be used.





                                    - 9 -       Formatted:  January 18, 2018






 TUSC(1)                                                             TUSC(1)
                    Not currently an official HP product



      Newer versions of tusc print user, interrupt and elapsed times upon
      exit when syscall statistics are requested. If the TUSCNOUSTATS
      variable is set to true, this additional information won't be printed.

      By default, the -T hires prints the time starting at the current time.
      If the TUSCTRUSSTIMESTAMPS variable is set to true, it will start at
      zero like the -d option of truss does.

      On 11.23 and newer systems, lwp_create causes a syscall return event
      to be generated by the kernel, in the context of the newly created
      thread, before that thread executes any syscall. Setting
      TUSCLWPCREATECHILD to true will cause this event to be reported.

 AUTHOR
      Written by Chris Bertin (HP).

      IPF disassembler contributed by Steven M. Valentine (HP).

      Copyright (c) 1996-2011 Hewlett-Packard Development Company, L.P.

 DISCLAIMER
      Tusc is not an official Hewlett-Packard product. As such, it is
      delivered "as is" with no expressed or implied warranty and is a "use
      at your own risk" tool.






























                                   - 10 -       Formatted:  January 18, 2018