bpxtrace — Activate or deactivate traces for processes

Format

  • bpxtrace –a [-B debug] [-p pid] [-u userid]
  • bpxtrace –c
    • [–f format|full|short|counts]
    • [–o outputpath] [–T tempdir] [–v volser]
    • [–B debug] [–h columns] [–x]
    • [command]
  • bpxtrace –e [-p pid] [-u userid]
    • [–f format|full|short|counts]
    • [–o outputpath] [–T tempdir] [–v volser]
    • [-B debug] [–h columns] [–x]
  • bpxtrace –i [-p pid] [-u userid]
    • [–f format|full|short|counts]
    • [–o outputpath] [–T tempdir] [–v volser]
    • [-B debug] [–h columns] [–x]
  • bpxtrace –s [-B debug] [-p pid] [-u userid]
  • bpxtrace –S
    • [–o outputpath] [–T tempdir]
    • [–B debug] [–v volser]
  • bpxtrace –t <seconds> [-p pid] [-u userid]
    • [–f format|full|short|counts]
    • [–o outputpath] [–T tempdir] [–v volser]
    • [-B debug] [–h columns] [–x]

Description

bpxtrace activates and deactivates tracing for one or more processes. It can be run from the z/OS® UNIX shell or the TSO environment. The captured syscall trace output is dependent on the system-wide setting for SYSOMVS CTRACE options and the amount of z/OS UNIX activity on the system when the bpxtrace command is issued.

Guideline: When using SYSOMVS CTRACE, always specify the minimal setting. Otherwise, when you run bpxtrace to capture syscall data, the amount of the output might be reduced.

Restriction: A single user can run bpxtrace only once at any given time. Running multiple occurrences might result in allocation errors, dump failures, inconsistent process tracing, or other unexpected behaviors.

The bpxtrace command might allocate the following temporary data sets:
  • userid.BPXGDCORE.DUMPDS
  • userid.BPXGDCORE.LOG
  • userid.BPXGDCORE.BPXEXEC
  • userid.BPXGDCORE.DDIR
The userid prefix is the MVS™ user name of the user running the command and is not affected by the current TSO prefix setting. The caller must have authority to create these data sets or the bpxtrace command will fail.

The data set names must be eligible for allocation on the specified or default volumes, or the bpxtrace command will fail. For example, any ACS routines that determine the SMS classes and storage groups for these data sets and objects might need to be modified to allow allocation on these volumes.

Options

While all options and parameters are accepted for each function, some might be ignored for a particular function. See the function descriptions in Format for options that are applicable to that particular function.

-a
Stops tracing without producing trace output.
-B debug
Used when diagnosing problems running bpxtrace.

Restriction: This option is intended for use by service personnel only.

The debug level is specified as one of the following numbers:

1
Verbose mode
2
Verbose mode and traps REXX signals
3
Verbose mode, traps REXX signals, and retains the temporary files and data sets
4
Verbose mode, traps REXX signals, retains the temporary files and data sets, and does not disable tracing for the bpxtrace command itself
-c command
Traces the shell command or script that is specified by the command string invoked by the /bin/sh -c command.
-e
Ends the tracing of user processes and produces trace output.
–f format|full|short|counts

Specifies how the trace records (syscall entry and syscall exit records) should be displayed. The values full, short, and counts show the trace records as formatted by the IPCS CTRACE command with the corresponding IPCS format request for COMP(SYSOMVS).

  • format processes the trace records and displays one line per trace record formatted with relevant information from the trace record. The format value is also filtered based on the user ID or process ID value that was specified. The following screen shows an example of output from bpxtrace -f format: 
    PID ASID TCB    Local time      System call    Additional trace data     
  7 0025 8FF1D8 09:43:04.070651 Call open      pgm=/bin/bpxtrace parms: 0000000D /bin/bpxwrtso 00800002
                                               00000000 00000000 00000000 00000000 
  7 0025 8FF1D8 09:43:04.070668 Exit open      rv=00000007 pgm=/bin/bpxtrace
  7 0025 8FF1D8 09:43:04.070675 Call read      pgm=/bin/bpxtrace parms: 00000007 25D00000 00000000 00001000
                                               00000000 00000000 00000000 
  7 0025 8FF1D8 09:43:04.091468 Exit read      rv=00001000 pgm=/bin/bpxtrace</xmp></entry>

    The first word of the "System Call" column identifies whether the trace entry corresponds to a syscall entry (CALL) or syscall exit (EXIT). The second word identifies the syscall. For "CALL" type entries, parameters shown in the "Additional Trace Data" column must be matched with the input and output parameters for the specified syscall. Note that the output parameters might contain residual data upon entry to a syscall. The pgm=field displays information about the process being traced only if it remains active after bpxtrace has ended. For "EXIT" type entries, the return value (RV) returned from the syscall is displayed in the "Additional Trace Data" column. Both the input parameter mapping and the return value meaning can be found in z/OS UNIX System Services Programming: Assembler Callable Services Referencez/OS UNIX System Services Programming: Assembler Callable Services Reference.

  • full corresponds to the full format option of the IPCS CTRACE command when specified with the KERNINFO option.

    Restriction: This option is intended for use by service personnel only.

    CTRACE COMP(SYSOMVS) FULL OPTIONS((KERNINFO))
    The following screen shows an example of output from bpxtrace -f full: 
     FCN...open             SYSCALL...BPX1OPN  PID...00000007  MODULE...BPXJCPC 
SY1       SYSCALL   0F080001  09:43:04.070651  STANDARD SYSCALL ENTRY TRACE 
    ASID..0025      USERID....MEGA      STACK@....26D9D0A8                  
    TCB...008FF1D8  EUID......00000000  PID.......00000007                  
   +0000  00000026  00000000  D1C3E2C5  8C000004  | ........JCSE.... |      
   +0010  8000000C  00000000  8288B768  FFFFFFFF  | ........bh...... |      
   +0020  00000002  26D9E8B4  00000000  7F6DCBBC  | .....RY....."_.. |      
   +0030  C0000007  0000000D  61828995  618297A7  | {......./bin/bpx |      
   +0040  A699A3A2  96000000  00800002  00000000  | wrtso........... |      
   +0050  00000000  00000000  0BBD0000  00000000  | ................ |      
   +0060  00000000  00000000  00000000  00000000  | ................ |      
   +0070  00000000  00000000  00000000  00000000  | ................ |      
   +0080  00000000  00000000  00000000            | ............     |  
FCN...open             SYSCALL...BPX1OPN  PID...00000007  MODULE...BPXJCPC
SY1       SYSCALL   0F080002  09:43:04.070668  STANDARD SYSCALL EXIT TRACE 
    ASID..0025      USERID....MEGA      STACK@....26D9D0A8                 
    TCB...008FF1D8  EUID......00000000  PID.......00000007                 
   +0000  00000026  00000000  D1C3E2C5  8C008000  | ........JCSE.... |     
   +0010  8000000A  00000000  00000007  00000002  | ................ |     
   +0020  00000001                                | ....             |  
  FCN...read             SYSCALL...BPX1RED  PID...00000007  MODULE...BPXJCPC
 SY1       SYSCALL   0F080001  09:43:04.070675  STANDARD SYSCALL ENTRY TRACE
     ASID..0025      USERID....MEGA      STACK@....26D9D0A8                 
     TCB...008FF1D8  EUID......00000000  PID.......00000007                 
    +0000  0000002B  00000000  D1C3E2C5  8C000004  | ........JCSE.... |     
    +0010  8000000C  00000000  82885438  00000000  | ........bh...... |     
    +0020  00000000  618297A7  00000000  7F6DCBBC  | ..../bpx...."_.. |     
    +0030  40000007  00000007  25D00000  00000000  |  ........}...... |     
    +0040  00001000  00000007  00000000  0BBD0000  | ................ |     
  FCN...read             SYSCALL...BPX1RED  PID...00000007  MODULE...BPXJCPC
 SY1       SYSCALL   0F080002  09:43:04.091468  STANDARD SYSCALL EXIT TRACE 
     ASID..0025      USERID....MEGA      STACK@....26D9D0A8                 
     TCB...008FF1D8  EUID......00000000  PID.......00000007                 
    +0000  0000002B  00000000  D1C3E2C5  8C008000  | ........JCSE.... |     
    +0010  8000000A  00000000  00001000  26D9D0BA  | .............R}. |     
    +0020  00000000                                | ....             |
  • short corresponds to the IPCS CTRACE command short format option: 
     CTRACE COMP(SYSOMVS) SHORT

    For an example of the SYSOMVS trace record when the short format option is specified, see z/OS MVS Diagnosis: Tools and Service Aids.

  • counts corresponds to the IPCS CTRACE command SYSOMVS sccounts option 
    CTRACE COMP(SYSOMVS) OPTIONS((SCCOUNTS))

    For an example of the SYSOMVS trace record when the sccounts format option is specified, see z/OS MVS Diagnosis: Tools and Service Aids.

The default is –f format.
–h columns
Selects the columns for trace output when –f format is used. columns is specified as a string of characters where each character represents a column.
p
PID column
a
ASID column
t
TCB column
l
Local time column
s
System call column
d
Additional trace data
The characters can be specified in any order but the column order in the output is not affected. An incorrect specification for the columns causes the default to be used. The default is -h patlsd.
-i
Produces trace output, leaving trace enabled.
–o outputpath
Specifies the path name of the z/OS UNIX file to contain the trace output. The default is to write the trace records to the standard output stream, which might cause a significant amount of trace output. When running in a shell environment, stdout can be redirected to a file; otherwise you can use the -o option to avoid having the output written to your session.

If the specified file exists, the contents are replaced. If redirection is used, the results depend on the redirection operator.

–p pid,...
Specifies the process ID of the process to have trace started, stopped, or formatted. When formatting a trace, the default formatting shows only the records for the processes that are identified by the list of specified PIDs. To have a list of multiple processes traced, specify multiple -p pids instances on the command. By default, tracing is started for all processes for the user.
-s
Starts tracing user processes.
-S
Produces trace output for unusual or unexpected conditions reported by the System Authorization Facility (SAF). To avoid flooding its trace with SAF results, z/OS UNIX traces only those conditions where the callable service documentation and return values do not provide enough information to determine the cause of the problem.

Users with an effective UID of 0 will see the trace records for all UIDs while non-effective UID 0 users will see only those trace records with a matching UID. The first 40 (decimal) bytes of these trace records are mapped by the ThliSecErrCT section of the BPXYTHLI macro, which is documented in z/OS UNIX System Services Programming: Assembler Callable Services Reference. The portion of the records beyond the first 40 bytes are for use by IBM® service.

The trace facilities utilized by the -S option do not require the prior activation of tracing for the system or for a given process. The trace facilities that are used for the -S option are always active and do not need to be activated or deactivated.

The following z/OS UNIX services create trace records for unusual or unexpected conditions reported by SAF:
  • BPX1PWD (__passwd)
  • BPX1SUI (setuid)
  • BPX1SEU (seteuid)
  • BPX1SRU (setreuid)
  • BPX1TLS (pthread_security)
  • BPX1GGN (getgrnam)
  • BPX1GGR (getgroups)
  • BPX1SEC (__login)
-t seconds
Traces for a specified period and then produces output. At the end of the time period, the traced processes will no longer have tracing on.
-T tempdir
Specifies the path name of the directory to be used for temporary files. By default, if bpxtrace is running in a shell environment, it uses the TMPDIR environment variable if available. Otherwise, /tmp is used.
–u userid
Specifies the user ID that is used in processing the trace. If the user ID is not the same as that of the invoking user, bpxtrace attempts to switch to UID(0) before determining which processes are to be traced. If the invoking user does not have permission to switch to UID(0), the bpxtrace command will fail. If both -p and -u are specified, -u is ignored.
–v volser
Specifies the volume to use for allocating temporary data sets. If -v is not specified, unit(sysallda) is used.
-x
Specifies that the output contains only exit trace lines. -f format must also be specified.

Examples

  1. To trace the calls made by the df utility and capture the output in a file: 
    bpxtrace -c -o trace.output df

Usage notes

If the user's effective UID is changed after BPXTRACE tracing started, CTRACE records might be missing from the BPXTRACE output. Due to limitations in DUMP processing, only CTRACE records matching the user's EUID at the time of the dump are captured and made available for display.

Exit values

0
Successful completion
1
The trace was successful but a listing was not generated
3
Command-line syntax error
4
Data set or file allocation error
5
The seteuid failed
8
z/OS UNIX callable service BPXGMCDE (MVS IPCS dump open/close service) open failure. This error indicates that the dump data set could not be opened. Try the command again. If the error persists, contact IBM Service.
9
z/OS UNIX callable service BPXGMPTR (Ptrace IPCS dump access service) command failure. This error indicates that a resource constraint was encountered while attempting to process the dump. Try the command again. If the error persists, contact IBM Service.
12
Review the error log to determine the problem.
Parent topic: Shell command descriptions