dbx - Use the debugger

Format

dbx [options] [executable-file [program-arguments ...]]
dbx [options] [attach-type] process-id
dbx [options] -C core-file

Description

dbx is a source-level debugger for z/OS® UNIX System Services. It provides an environment to debug and run C and C++ programs, as well as performing machine level debug. You can carry out operations such as the following:
  • Examine object files.
  • Run a program in a controlled environment.
  • Set breakpoints at selected statements or run the program one line at a time.
  • Debug using symbolic variables and display them in their correct format.
  • View an MVS™ dump.
  • Attach to a running program, and perform debugging operations.
The executable-file argument is an load module produced by a compiler. To perform source-level debugging, you need to compile your executable with symbolic information. This is accomplished by specifying the -g or -Wc,debug compiler flags on the compiler command line.
Note: If the object file is not compiled with the -g or -Wc,debug option on the c89/cc/c++ command, or if the user compiles with optimization, the capabilities of the dbx command will be reduced.

The core-file argument is an MVS dump that exists as a file in the z/OS UNIX file system or in an MVS data set.

dbx allows the end user to customize its behavior via two files that are processed during initialization. These are .dbxsetup. Each file can contain a list of dbx subcommands that will be run before the dbx prompt is displayed. During startup, dbx will first search for these files in the current working directory and then in the user's $HOME directory. If a file is found, it is parsed and the search for that specific file terminates. Use a text editor to create a .dbxsetup or .dbxinit file.

Any subcommand in the .dbxsetup file are executed before the debug target program is loaded. This allows the user to tailor dbx's operational behavior during this phase of the dbx startup process. Any subcommand in the .dbxinit file are executed just before the dbx prompt is displayed.

You can use the man command to view descriptions of dbx subcommands. To do this, you must prefix all subcommands with dbx. For example, to view a description of the dbx alias subcommand, you would enter the following: 
man dbxalias

dbx supports SVC dumps and SYSMDUMP dumps. It does not process SYSUDUMP dumps or CEEDUMP dumps. (The dump data set must be FB with a record length of 4160.)

Attach-types

-a ProcessID
Attaches the debug program to a running process. The debug program becomes active as soon as the process wakes up. To attach the debug program, you need authority to use the kill command on this process.
-A ProcessID
Reattaches the debug program to a running process that is already being debugged by dbx . Use this option to reattach a child process that was created when a debugged parent process did a fork while multiprocess debugging mode was active. To reattach to the debug program, you need authority to use the kill command on this process.

Options

-b
Suppresses processing of .dbxsetup and .dbxinit files (bare startup).
-c script
Runs dbx subcommands from a specified script file before reading from standard input.
-C dump-filename
Puts dbx in dump reading (core file) processing mode.
-d
Deprecated. This option is ignored and remains only for compatibility purposes.
-f
Deprecated. This option is ignored and remains only for compatibility purposes.
-F
Starts debug target in a different address space than the one dbx currently resides in; or starts dbx in its own address space when attaching to a running target program.
-h
Prints the dbx command syntax.
-I directory
Appends the given directory to the list of directories searched for source and debug files. The default list contains the working directory and the directory containing the object files. The search path can also be set with the use subcommand.
-m dbxmode
Instructs dbx to start in a specific mode:
  • Specifying -m4 forces dbx to run in 31-bit mode, even on a machine capable of running it in 64-bit mode.
  • Specifying -m8 forces dbx to run in 64-bit mode. If this is impossible, dbx will terminate.
-p ipaddress | name[:port]
Tells dbxto open a socket and connect to the ipAddress:port or machineName:port which is assumed to be a GUI that supports remote debugging. For example: dbx -p 9.123.456.78:8001 mypgm. In this mode, the command-line prompt is not displayed and the user cannot enter dbxsubcommands through the command-line interface. In addition, the following dbx subcommands are not supported when entered via a GUI debug console (command line) interface: detach, edit, multproc, object, quit, rerun, run, sh.

If :port is not specified, port 8001 is used as the default.

-q
Suppresses some of the dbx startup messages. Only the dbx version information is printed before the prompt is displayed. All other messages are suppressed. This option does not affect the verbosity of normal dbx operation.
-r
Runs the object file immediately. If it ends successfully, the dbx debug program is exited. Otherwise, the debug program is entered and the reason for termination is reported.
Unless -r is specified, the dbx command prompts the user and waits for a command. However, you can specify program arguments on the .dbxsetup files that are used by dbx and .dbxinit even when -r is not used. For example: 
dbx myprog arg1 arg2 arg3
-u
Deprecated. This option is ignored and remains only for compatibility purposes.

Expression handling

Specify expressions in dbx with a subset of C and Pascal syntax. A prefix * (asterisk) or a postfix ^ (circumflex) denotes indirection. Specify portions of an array by separating the lower and upper bounds with .. (two periods).

Use [ ] (square brackets) or ( ) (parentheses) to enclose array subscripts. Use the field reference operator . (period) with pointers and records. The field reference operator . (period) makes the C operator → unnecessary (although it is supported).

When displaying variables and expressions, the dbx command resolves names first using the static scope of the current function. The dynamic scope is used if the name is not defined in the first scope. If static and dynamic searches do not yield a result, an arbitrary symbol is chosen and the system prints the message (using Module.Variable). The Module.Variable construction is the name of an identifier qualified with a block name. Override the name resolution procedure by qualifying an identifier with a block name. Source files are treated as modules named by the file name without the language suffix (such as the .c suffix on a C language program).

The dbx command debug program checks types of expressions. Override types of expressions by using TypeName (Expression). When there is no corresponding named type, use the &TypeName special construct to represent a pointer to the named type. Represent a pointer to enum, struct, or union tag with the $$TagName construct.

A condition can be any dbx expression that evaluates to a true or false value. This pertains to four dbx subcommands: stop, stopi, trace, and tracei.

The following operators are valid in expressions:
Expression Operators
exp (exponentiation) Algebraic + (addition), - (subtraction), * (multiplication), / (floating point division), div (integral division), mod (modulo division), exp (exponentiation)
Bitwise ? (unary minus), ? (bitwise or), & (bitwise and), ? (bitwise xor), ~ (one's complement), << (bitwise left shift), >> (bitwise right shift), bitand (bitwise and), xor (bitwise xor)
Logical ?? (logical or), && (logical and), ! (logical not), or, and, not
Comparison < (less than), > (greater than), <= (less than or equal to), >= (greater than or equal to), <> (not equal to), != (not equal to), = (equal to), == (equal to)
Other sizeof

Files

a.out
The object file a.out is the default name of an executable file produced by the compiler. If no executable is specified on the dbx command line, then dbx will look for an a.out file to debug.
.dbxinit
Contains initial commands.
.dbxsetup
Contains initial commands.
.dbxhistory
Contains a listing of recently used dbx commands. Used by the history dbxsubcommand.

Examples

  1. This example shows you how to attach dbx to a running process. To do this, it is useful to insert a sleep(30) call into the program to be debugged. This will give you enough time to issue the ps -Aef shell command to find the process ID of the program. Once you have the process ID, issue the shell command: dbx -a process-id.
    Before starting the server, set the following four environment variables:
    • export _BPX_PTRACE_ATTACH=yes (tells the kernel to always load DLLs and executables into read/write storage)
    • export _CEE_RUNOPTS="test(all)" (tells Language Environment® to load the CEEEVDBG debugger exit and send dbx debug events)
    • export _CEE_DEBUG_FILENAME31=/bin/dbx31vdbg (the path to the Language Environment debugger exit for 31-bit programs)
    • export _CEE_DEBUG_FILENAME64=/bin/dbx64vdbg (the path to the Language Environment debugger exit for 64-bit programs)

    Use dbx commands to set breakpoints, step through program statements, print variables, work with threads, examine storage, and actions as needed.

  2. Example of creating the .dbxinit file in your home directory: 
    alias nsf "use /sandbox3/UNIX_notes/CGOOD/notes/nsf/"
alias asc "set $asciichars ; set $asciistrings"
alias ebc "unset $asciichars ; unset $asciistrings"
set $repeat
set $history_unique
set $hold_next
set $showbases
  3. Sample dbx commands issued after starting server and seeing the sleeping for 30 seconds message for server process ID 50331876: 
    /sandbox3/UNIX_notes/CGOOD/notes/os>  dbx -a 50331876
FDBX0278: Waiting to attach to process 50331876 ...
FDBX0089: dbx for MVS.
FDBX0399: Compiled: Sep 28 2001 10:22:24 GMT as BFP
FDBX0400: OS level: 12.00 03, LE level: 4.1.2 with CWIs.
FDBX0100: Type 'help' for help.
FDBX0099: reading symbolic information ...
FDBX0900: reading symbols for 
/sandbox3/UNIX_notes/CGOOD/usr/lpp/lotus/notes/latest/os390/server ...
FDBX0037: XPLink module found
FDBX0900: reading symbols for 
/sandbox3/UNIX_notes/CGOOD/usr/lpp/lotus/notes/latest/os390/libnotes ...

attached in sleep at 0xebcd024 ($t1)
sleep() at 0xebcd024
unnamed block $b64, line 873 in "meminit.c"
MemoryInit1(), line 873 in "meminit.c"
OSInitExt() at 0x1000cdc4
ServerMain() at 0xf80ac38
main() at 0xf80a12e
.() at 0xeeb2f4a
.() at 0x6f8e976
0x0ebcd024 (+0xff3c3024) 47060003     nop    X'3'($r6,)
(dbx) stop at "meminit.c":875
[1] stop at "meminit.c":875
(dbx) c
[1] stopped in unnamed block $b64 at line 875 in file "meminit.c" ($t1)
(dbx) where
unnamed block $b64, line 875 in "meminit.c"
MemoryInit1(), line 875 in "meminit.c"
OSInitExt() at 0x1000cdc4
ServerMain() at 0xf80ac38
main() at 0xf80a12e
.() at 0xeeb2f4a
.() at 0x6f8e976
(dbx) list 872,875
  872           __printf_a("sleeping for 30 seconds time to dbx\n");
  873           sleep(30);
  874           __printf_a("Done sleeping \n");
  875           if (loc_num_of_segs > MAX_NUM_OF_SEGM)
(dbx) print loc_num_of_segs
4 
(dbx) &loc_num_of_segs/8x
0fc55af8:  0000 0004 0000 01b0 0400 0000 0f9d 57f8
(dbx) 0xfc55af8/8x
0fc55af8:  0000 0004 0000 01b0 0400 0000 0f9d 57f8
(dbx) n
stopped in unnamed block $b64 at line 971 in file "meminit.c" ($t1)
  971   DoAgain2:
(dbx) n
stopped in unnamed block $b64 at line 972 in file "meminit.c" ($t1)
  972                   hMMShMemId = shmget(ShmemAccessKey, 
FirstSegSize, IPC_CREAT|IPC_EXCL|loc_shm390flags|perms);

Usage notes

The following dbx subcommands can have their output redirected to a file.
  • alias
  • args
  • condition
  • dump
  • examine
  • list
  • listfiles
  • listfuncs
  • listi
  • map
  • mutex
  • onload
  • readwritelock
  • rerun
  • registers
  • run
  • sh
  • status
  • thread
  • whatis
  • where
  • whereis
  • which
The following dbx subcommands will return an error message in GUI mode (-p).
  • detach
  • edit
  • multproc
  • object
  • quit
  • rerun
  • run
  • sh

Related information

c89/cc/c++