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.
- userid.BPXGDCORE.DUMPDS
- userid.BPXGDCORE.LOG
- userid.BPXGDCORE.BPXEXEC
- userid.BPXGDCORE.DDIR
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
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.
The following display shows an example of output from bpxtrace -f full:CTRACE COMP(SYSOMVS) FULL OPTIONS((KERNINFO))
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.
- 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:
- –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
- -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
- 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.