


 xdb(1)                                                               xdb(1)




 NAME
      xdb - C, FORTRAN, Pascal, and C++ Symbolic Debugger

 SYNOPSIS
      xdb [-d dir] [-r file] [-R file] [-p file] [-P process_ID] [-L] [-l
      library]
          [-i file] [-o file] [-e file] [-S num] [-s] [objectfile [corefile]]

 DESCRIPTION
      xdb is a source level debugger for C, HP FORTRAN, HP Pascal, and C++
      programs.  It provides a controlled environment for their execution.
      See the HP-UX Symbolic Debugger User's Guide for a comprehensive
      description of xdb .

      objectfile is an executable program file having zero or more of its
      component modules compiled with the debug option turned on (enabled by
      the -g option of the cc, f77, pc, and CC compilers).  The support
      module /usr/lib/end.o must be included as the last object file linked,
      except for libraries included with the -l option to ld (see ld(1)).
      The support module is included automatically when ld is invoked as
      part of a compile command that uses the -g option.  The default for
      objectfile is a.out.  Note that by default ld links in shared
      libraries instead of archive libraries.

      corefile is a core image from a failed execution of objectfile.  The
      default for corefile is core.

    Options
      xdb recognizes the following options:

           -d dir         Specify dir as an alternate directory where source
                          files are located.

           -r file        Specify a record file, which is invoked
                          immediately (for overwrite, not for append).

           -R file        Specify a restore state file, which is processed
                          before the -p option (if any) and after the -r
                          option (if any).

           -p file        Specify a playback file which is invoked
                          immediately.

           -P process_ID  Specify the process ID of an existing process the
                          user wants to debug.

           -L             Use the line-oriented interface.

           -l library     Pre-load information about this shared library, -l
                          ALL means always pre-load shared library
                          information.



 Hewlett-Packard Company            - 1 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




           -i file        Redirect standard input to the child process from
                          the designated file or character device.

           -o file        Redirect standard output from the child process to
                          the designated file or character device.

           -e file        Redirect standard error from the child process to
                          the designated file or character device.

           -S num         Set the size of the string cache to num bytes
                          (default is 1024, which is also the minimum).

           -s             Enable debugging of shared-libraries.

      At start-up, the debugger executes commands from the file
      $HOME/.xdbrc, if it exists.

 ENVIRONMENT VARIABLES
    Display
      TERM           This variable specifies the terminal type.  There is no
                     default for the terminal type.

      LINES          This variable specifies the window height in lines of
                     text.  The default for this variable is 24 if not
                     otherwise determinable.

      COLUMNS        This variable specifies the window width in text
                     columns.  The default for this variable is 80 if not
                     otherwise determinable.

    Command Line Editing
      XDBHIST        This variable specifies the history file.  The default
                     for this variable is $HOME/.xdbhist.

      HISTSIZE       This variable specifies the actual number of commands
                     allowed in the history file.  The default for this
                     variable is 128.

      XDBEDIT        This variable specifies the editing mode ( vi, emacs,
                     or gmacs).  The default for this variable is to match
                     the environment variable VISUAL or EDITOR; otherwise,
                     there is no default.

    Native Language Support
      LANG           This variable determines the local language equivalent
                     of y (for yes/no queries).  LANG also determines the
                     locale in which messages are displayed.  The default
                     value for this variable is C.

      LC_CTYPE       This variable determines the interpretation of text as
                     single- and/or multi-byte characters and their



 Hewlett-Packard Company            - 2 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




                     printability when reading or writing character and
                     string data.  If LC_CTYPE is not specified in the
                     environment or is set to the empty string, the value of
                     LANG is used as the default.

    International Code Set Support
      Single- and multi-byte character code sets are supported.

 LOCATION SYNTAX
      line           A number that refers to a particular line in a file.

      location       A particular line in a file and its corresponding
                     address in the user's program.  location has the
                     following general forms:

                          line
                          #label
                          file[:line]
                          [file:]proc[:proc[...]][:line| #label]
                          [class]::proc[:line| # label]

                     To reference code addresses symbolically, use:

                          proc#line
                          [[class]::]proc#line

 Variable Identifiers
      Variables are referenced exactly as they are named in the source file
      or files.  Uppercase/lowercase sensitivity is controlled by the tc
      command.

      Several methods can be used to obtain the value of some variable var,
      depending on where and what it is:

      var               Search for var first as a local in the current
                        procedure (or the most recent instance of the
                        current procedure), next as a member of that
                        procedure's class, or finally as a global.

      class::var        Search class for variable.

      proc:var
      [[class]::]proc:[class::]var
                        Search for var in the current or most recent
                        instance of proc.  A leading :: indicates a global.

      proc:depth:var
      [[class]::]proc:depth:[class::]var
                        Use the instance of proc that is at depth depth
                        (exactly), instead of the current or most recent
                        instance.



 Hewlett-Packard Company            - 3 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      :var
      ::var             Search for a global (not local) variable named var.

      .                 dot is shorthand for the last thing viewed.

 Special Variables
      Special variables are names for things that are not normally directly
      accessible.  Special variables include:

      $var              The debugger has room in its own address space for
                        several user-created special variables of type long
                        .

      $pc, $sp, $r7, etc.
                        These are the names of the program counter, the
                        stack pointer, the CPU general registers, etc.

      $result           This is used to reference the return value from the
                        last command-line procedure call.  It can also be
                        referenced as $short and $long.

      $signal           This lets you see and modify the current child
                        process signal number.

      $lang             This lets you see and modify the current language.
                        Possible values are: C, C++, FORTRAN, Pascal,
                        default.

      $depth            This is the default stack level for viewing local
                        variables.

      $print            Alters the behavior of the ``print'' command when
                        printing character data.  Values that can be
                        assigned are ascii, native, and raw.

      $line             This lets you see and modify the current source line
                        number.

      $malloc           This lets you see the current amount of memory
                        (bytes) allocated at run-time for use by the
                        debugger itself.

      $step             This lets you see and modify the number of machine
                        instructions the debugger steps while in a non-
                        debuggable procedure before setting an up-level
                        breakpoint and free-running to it.

      $cplusplus        This is interpreted as a set of flags to control
                        behavior of certain C++ capabilities.





 Hewlett-Packard Company            - 4 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




                             bit 0     Set means print full base class
                                       information at each occurrence.

                             bit 1     Set means bpc sets breakpoints on
                                       member functions of base classes,
                                       also.

                             bit 2     Set means bi sets breakpoints on
                                       member functions of base classes,
                                       also.

                        The default for all bits is clear.  Some commands
                        take a -c or -C argument which causes the action to
                        be as if the appropriate bit of $cplusplus was clear
                        (-c) or set (-C).

 COMMANDS
      The debugger has a large number of commands for viewing and
      manipulating the program being debugged.  They are explained below and
      are grouped according to functional similarity.

    Window Mode Commands
      These commands control what is displayed in the source window.  The
      source window by default comes up in source mode for viewing source
      code.  If assembly language instructions are needed, the disassembly
      mode can be selected.  Registers are also shown in this mode.  If both
      assembly instructions and source code are needed, the split-screen
      mode can be selected.  Commands are as follows:

           td          Toggle disassembly mode.

           ts          Toggle split-screen mode.

           gr          Display the general registers when the debugger is in
                       disassembly (non-split-screen) mode.

           fr          Display the floating-point registers when the
                       debugger is in disassembly (non-split-screen) mode.

           +r          Scroll the floating-point register display forward
                       four lines.

           -r          Scroll the floating-point register display back four
                       lines.

           w [size]    Set the size of the source viewing window.

           u           Update the screen to reflect the current location.

           U           Clear and redraw the screen.




 Hewlett-Packard Company            - 5 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




    Path Map Commands
      Path maps can be used to redirect portions of a source tree to
      different directories.  Commands are as follows:

      apm old_path [new_path]
                            Add a path map to the list of path maps.

      lpm                   List path maps.  The list is numbered for use
                            with the dpm command.

      dpm [number | *]      Delete path map.  Default number is 1 (most
                            recent path map).  A * deletes all path maps.

      D directory           Adds directory to the list of alternate
                            directory search paths for source files.

    File Viewing Commands
      These commands may change the current viewing position, but they do
      not affect the next statement to be executed in the child process, if
      any.  Commands are as follows:

      v                 View the source one window forward from the current
                        source window.

      v location        View the source at the specified location, placing
                        it in the center of the window.

      V [depth]         View the source at the current procedure at depth on
                        the stack.

      va [address]      View the assembly code at address in the source
                        window (see the td command).

      L                 Display the file name, procedure name, line number,
                        and the current source statement corresponding to
                        the object code being executed or examined.

      + [lines]         Move to lines (default one) lines after the current
                        line.

      - [lines]         Move to lines (default one) lines before the current
                        line.

      / [string]        Search forward through the current file for string,
                        starting at the line after the current line.

      ? [string]        Search backward for string, starting with the line
                        before the current line.

      n                 Repeat the previous / or ? command using the same
                        string as the last search, starting at the current



 Hewlett-Packard Company            - 6 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




                        location being viewed.

      N                 The same as n, but the search goes in the opposite
                        direction from that specified by the previous / or ?
                        command.

    Display Formats
      The display formats tell the debugger's data viewing commands how
      output should be formatted.  A format is of the form
      [count]formchar[size].  For example, p abc\4x2 prints, starting at the
      location of abc, four two-byte numbers in hexadecimal.

      Formats that print numbers use lowercase characters to represent
      integer data types and uppercase to represent long data types.  For
      example, O prints in long octal.

      The following formats are available:

           n         Print in the ``normal'' format, based on the type.
                     Arrays of char and pointers to char are interpreted as
                     strings, and structures are fully dumped.

           (d|D)     Print in decimal (as integer or long).

           (u|U)     Print in unsigned decimal (as integer or long).

           (o|O)     Print in octal (as integer or long).

           (x|X)     Print in hexadecimal (as integer or long).

           (z|Z)     Print in binary (as integer or long).

           (b|B)     Print a byte in decimal (either way).

           c         Print a character.

           C         Print a wide-character.

           (e|E)     Print in ``e'' floating-point notation (as float,
                     double, or long).

           (f|F)     Print in ``f'' floating-point notation (as float,
                     double, or long double).

           (g|G)     Print in ``g'' floating-point notation (as float,
                     double, or long double).

           i         Print a disassembled machine instruction.

           a         Print a string using expr as the address of the first
                     byte.



 Hewlett-Packard Company            - 7 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




           w         Print a wide-character string using expr as the address
                     of the first element.

           W         Print a wide-character string using expr as the address
                     of a pointer to the first element.

           r         Print the template of an object (C++).

           R         Print the template of an object with base classes
                     displayed (C++).

           s         Print a string using expr as the address of a pointer
                     to the first byte.

           t         Show the type of expr (usually a variable or procedure
                     name).

           T         This is identical to the t format except for C++
                     classes and struct objects where base class and struct
                     type information are also displayed.

           p         Print the name of the procedure containing address
                     expr.

           S         Do a formatted dump of a structure.

           k         Identical to the S format.

           K         Same as the S format, except that for C++ class and
                     struct objects the base class and struct data are also
                     displayed.

      There are some short hand notations for size:

           b         1 byte (char).

           s         2 bytes (short).

           l         4 bytes (long).

           D         8 bytes (double).  Can only be used with floating-point
                     formats.

           L         16 bytes (long double).  Can only be used with
                     floating-point formats.

    Data Viewing and Modification Commands
      p expr            If expr does not resemble anything else (such as a
                        command), it is handled as if you had typed p expr\n
                        (print expression in normal format).




 Hewlett-Packard Company            - 8 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      p expr\format     Print the contents (value) of expr using format.

      p expr?format     Print the address of expr using format.

      p -[[\] format]   Back up to the preceding memory location (based on
                        the size of the last thing displayed) and use format
                        if supplied, or the previous format if not.

      p + [[\] format]  Go forward to the following memory location (based
                        on the size of the last thing displayed) and use
                        format if supplied, or the previous format if not.

      p class::         Print the values of all static data members of
                        class.

      pq argument       Print quietly (evaluate but do not print).  argument
                        can be anything allowed after p.

      l [proc[:depth]]
      l [[[class]::][proc[:depth]]]
                        List all parameters and local variables of the
                        current procedure (or of proc, if given, at the
                        specified depth, if any).

      la                List all assertions.
      lb                List all breakpoints.
      ld                List all directories (where to search for files).
      lsl               List all shared libraries known to the debugger.
      lz                List all zignals (signal actions).

      lc [string]       List all (or matching) common blocks in the current
                        procedure (FORTRAN).
      lf [string]       List all (or matching) files (source files used to
                        build objectfile).
      lg [string]       List all (or matching) global variables.
      ll [string][ @library]
                        List all (or matching) labels.
      lm [string]       List all (or matching) macros.
      lp [[class]::][string]
                        List all (or matching) procedure names.
      lr [string]       List all (or matching) registers.
      ls [string]       List all (or matching) special variables (except
                        registers).
      lx                List exception stop-on-throw and -catch state (C++).
      lcl [string]      List all (or matching) classes (C++).
      lct [string]      List all (or matching) class templates (C++).
      ltf [string]      List all (or matching) template functions (C++).
      lft [string]      List all (or matching) function templates (C++).
      lo [[class]::][string]
                        List all (or matching) overloaded functions (C++).




 Hewlett-Packard Company            - 9 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      mm [string]       Show a memory-map of all currently loaded shared-
                        libraries and the main program, or of the one
                        specified.
    Stack Viewing Commands
      t [depth]         Trace the stack for the first depth (default 20)
                        levels.
      T [depth]         Same as t, but local variables are also displayed,
                        using \n format (except that all arrays and pointers
                        are shown simply as addresses, and structures as
                        first word only).
      up [offset]       Move up (decreasing depth) offset levels in the
                        stack.  The default value of offset is 1.
      down [offset]     Move down (increasing depth) offset levels in the
                        stack.  The default value of offset is 1.
      top               Move to the top of the stack (this is the same as V
                        0).
      tst               Toggle the visibility of inter-procedural stubs in
                        stack traces (PA-RISC only).
    Job Control Commands
      These commands let you control execution of the program.  The parent
      (HP Symbolic Debugger) and child (objectfile) processes take turns
      running.  The debugger is only active and able to execute commands
      while the child process is stopped due to a signal or a breakpoint, or
      by terminating.
      r [arguments]     Run a new child process with the given or previous
                        argument list, if any.
      R                 Run a new child process with no argument list.
      k                 Terminate (kill) the current child process, if any.
      c [location]      Continue after a breakpoint or a signal, ignoring
                        the signal, if any.  If a location is specified, a
                        tempory breakpoint is set at that location.
      C [location]      Continue just like c, but allow the signal (if any)
                        to be received.  If a location is specified, a
                        tempory breakpoint is set at that location.
      s [count]         Single step 1 (or count) statements (or instructions
                        in disassembly mode).
      S [count]         Similar to s, but treat procedure calls as single
                        statements (do not step ``into'' them).  The s and S
                        commands pass the current signal (like C).  Set
                        $signal = 0 if necessary, to prevent this.
    Breakpoint Commands
      The debugger provides a number of commands for setting and deleting
      breakpoints.  Associated with any breakpoint are three attributes:
      location          A particular line in a file and its corresponding
                        address in the user's program, if executable code
                        exists for that line.
      count             The number of times the breakpoint is encountered
                        prior to recognition.  This can be suffixed with p
                        (permanent, which is the default) or t (temporary).
      commands          Actions to be taken upon recognition of a breakpoint
                        before waiting for command input.  This is a list of



 Hewlett-Packard Company           - 10 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




                        debugger commands separated by ; and enclosed by {}.
      Each breakpoint can be individually activated or suspended, and there
      is an overall breakpoint mode which can be toggled.  If any breakpoint
      is added or activated, or if all breakpoints are suspended, the global
      mode is toggled automatically.
      Here are the breakpoint commands:
      lb                List all breakpoints.
      b [location] [\count] [commands]
                        Set a permanent breakpoint at the current location
                        (or at location).
      db [number]       Delete breakpoint number number, or at the current
                        location.

      db *              Delete all breakpoints (including ``procedure''
                        breakpoints).

      bi expr.proc [\count] [commands]
                        After evaluating expr to what must be a class
                        instance, set an ``instance'' breakpoint at the
                        first executable line of proc for the instance's
                        class.

      bi [-c|-C] expr [commands]
                        After evaluating expr to what must be a class
                        instance, set ``instance'' breakpoints at the first
                        executable line of all member functions of the
                        instance's class.  The -c option indicates only
                        members of the designated class.  The -C option
                        indicates members of base classes as well as members
                        of the designated class.

      bpc [-c|-C] class [commands]
                        Set ``class'' breakpoints at the first executable
                        line of all member functions of class.  See the
                        previous command for information on -c and -C.

      bpo [[class]::]proc [commands]
                        Set ``overload'' breakpoints at the first executable
                        line of all overloaded functions with name proc
                        (which can be qualified by a class).

      bp [commands]     Set permanent breakpoints at the beginning (first
                        executable line) of every debuggable procedure.

      bpx [commands]    Set permanent breakpoints at the exit (final
                        executable statement) of every debuggable procedure.

      bpt [commands]    Set permanent breakpoints at the entry and exit
                        (first and final executable statement) of every
                        debuggable procedure.  The given commands are
                        associated with the entry breakpoint and default to



 Hewlett-Packard Company           - 11 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




                        Q;t 2;c

      dp                Delete all procedure breakpoints.

      Dpx               Delete all ``procedure exit'' breakpoints.

      Dpt               Delete all ``procedure trace'' breakpoints.

      abc commands      Define a global breakpoint command list to be
                        executed whenever any breakpoint is hit (normal,
                        instance, class, overload, procedure, procedure
                        exit, or procedure trace).

      dbc               Delete the global breakpoint command.

      bb [depth] [\count] [commands]
                        Set a breakpoint at the beginning (first executable
                        line) of the procedure at the given stack depth (if
                        depth is not given use the current procedure).

      bx [depth] [\count] [commands]
                        Set a breakpoint at the exit (last executable line)
                        of the procedure at the given stack depth (if depth
                        is not given use the current procedure).

      bu [depth] [\count] [commands]
                        Set an up-level breakpoint.

      bt [depth | proc] [\count] [commands]
                        Trace the current procedure (or procedure at depth,
                        or proc).  By default, the entry breakpoint commands
                        are Q;t 2;c , which shows the top two procedures on
                        the stack and continues.

      ba address [\count] [commands]
                        Set a breakpoint at the given code address.

      txc               Toggle the exception stop-on-catch state.

      txt               Toggle the exception stop-on-throw state.

      xcc [commands]    Define the stop-on-catch command-list.

      xtc [commands]    Define the stop-on-throw command-list.

      bc number count   Set the count of breakpoint number to count.

      sb [num]          Suspend the breakpoint having the num specified, or
                        if a num is not entered, the breakpoint at the
                        current line is suspended if one exists.




 Hewlett-Packard Company           - 12 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      sb *              Suspend all breakpoints.

      ab [num]          Activate breakpoint number num or if a num is not
                        entered, the breakpoint at the current line is
                        activated if one exists.

      ab *              Activate all breakpoints.

      tb                Toggle the overall breakpoint mode between active
                        and suspended.

    Auxiliary Breakpoint Commands
      if expr {commands} [{commands}]
                        If expr evaluates to a non-zero value, the first
                        group of commands (the first {} block) is executed;
                        otherwise it (and the following {, if any) is
                        skipped.

      Q                 If the Quiet command appears as the first command in
                        a breakpoint command list, the normal announcement
                        of breakpoint at address is not made.

      "any string you like"
                        Print the given string.

    Assertion Control Commands
      Assertions are command lists that are executed before every
      instruction.  If there is an active assertion, the program is single-
      stepped at the machine-instruction level and runs very slowly.

      Each assertion can be individually activated or suspended, and there
      is an overall assertions mode which can be toggled.  If any assertion
      is added or activated or if all assertions become suspended, the
      global mode is toggled automatically.

      Here are the assertion commands:

      a commands        Create a new assertion with the given command list
                        which is not parsed until it is executed.

      aa number         Activate assertion number.

      aa *              Activate all assertions.

      da number         Delete assertion number.

      da *              Delete all assertions.

      sa number         Suspend assertion number.





 Hewlett-Packard Company           - 13 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      sa *              Suspend all assertions.

      ta                Toggle the overall assertions mode between active
                        and suspended.

      x [mode]          Force an exit from assertions mode immediately
                        (default or mode is non-zero) or at the end of the
                        command list ( mode non-zero).

    Signal Control Commands
      These commands are used to modify and list the contents of the
      ``zignal'' (signal) handling table.  Here are the signal control
      commands:

       z [signal][ i ][ r ][ s ][ Q ]
                               Toggles flags ( ignore, report, or stop) for
                               signals ( Quietly).

      lz                       Lists the current handling of all signals.

    Record and Playback Commands
      These commands allow the recording of debugger sessions in a
      recordfile and the playing back of those sessions.  Here are the
      record and playback commands:

      >file             Set or change the recordfile to file and turn
                        recording on.

      >>file            Same as >file, but appends to file instead of
                        overwriting.

      >@file
      >>@file           Set or change the record-all file to file, for
                        overwriting or appending.

      >t                Turn recording on.
      >f                Turn recording off.
      >c                Close the recording file
                        When recording is resumed, new commands are appended
                        to the file.  In this context, >> is equivalent to
                        >.

      >@t               Turn record-all on
      >@f               Turn record-all off
      >@c               Close the record-all file

                        In this context, >>@ is equivalent to >@.

      tr [@]            Toggle recording [record-all]; if on, turn it off;
                        if off, turn it on.




 Hewlett-Packard Company           - 14 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      >                 Tell the current recording status (same as >>).

      >@                Tell the current record-all status (same as >>@).

      <file             Start playback from file.

      <<file            Start playback from file, using the single-step
                        feature of playback.

    Save State Command
      ss file           Save the current set of breakpoints, macros and
                        assertions in file for later use with the -R
                        command-line option.

    Macro Definition Commands
      def name [replacement-text]
                        Define name as a macro whose value is replacement-
                        text.

      undef name        Remove the macro definition from name so that name
                        no longer exists as a replacement string macro.

      tm                Toggle the state of the macro substitution mechanism
                        between active and suspended.

    Miscellaneous Commands
      sm                Suspend the built-in more pagination facility of the
                        debugger output.

      am                Activate the built-in more pagination facility to
                        paginate the debugger output.

      <carriage-return>
      ~                 Repeat the last command, if possible, with an
                        appropriate increment, if any.

      ! [command-line]  Invoke a shell program.

      # [text]          Flag text as a comment to be echoed to the command
                        window.

      f[printf-style-format]
                        Set the address printing format using printf(3S)
                        format specifications (not debugger format styles).
                        If no argument is provided, the format is set to the
                        default, %10.8lx .

      g (line|#label|+[lines]|-[lines])
                        Go to an address in the procedure on the stack at
                        depth zero (not necessarily the current procedure).




 Hewlett-Packard Company           - 15 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      h [topic]
      help [topic]      Print commands/syntaxes related to this topic using
                        more(1).  Use h help for a list of topics.

      I                 Print information (inquire) about the state of the
                        debugger and various toggles.

      M                 Print the current text (objectfile) and core
                        (corefile) address maps.

      tM                Toggle the address mapping of corefile between the
                        initial map and the modifiable mapping pair which
                        the user can set with the Mc command.

      M(t | c) [expr [; expr [ ... ]]]
                        Set the text (objectfile) or the modifiable core
                        (corefile) address map.

      q                 Quit the debugger.

      tc                Toggle case sensitivity in searches.

 ADOPTING AN EXISTING PROCESS
      The symbolic debugger (xdb) command line option -P process_ID allows
      for the debugging of a free-running process.  To adopt a process, the
      effective user IDs of the debugger and the process to be adopted must
      match, or the effective user ID of the debugger must be root.  When a
      process is adopted, it halts, and the debugger displays where the
      program is halted, at which point the program can be debugged.  If the
      user quits the debugger without killing the process, the debugger
      removes all breakpoints from the process and allows it to continue
      running.  If a program is designed to be adopted by the debugger when
      in a certain state (such as an error condition), it is important that
      the program do something such as enter an infinite loop, rather than
      calling the system routine sleep() (see sleep(3C)).  A sleeping
      program cannot be adopted correctly by the debugger, although a
      suspended process (i.e., blocked on a read) can be.

      When using the -s command-line option with xdb to debug shared
      libraries in an adopted process, prepare the executable_file by
      executing:

           pxdb -s on  executable_file

      Once the file is prepared for debugging, run executable_file in the
      background and adopt it using:

           xdb -s -P  process_ID executable_file

      The syntax for this use of the pxdb command is:




 Hewlett-Packard Company           - 16 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




           pxdb -s  [ on | enable ] file
                          Enables shared library debugging of the adopted
                          process by setting private data switches within
                          the file.

           pxdb -s  [ off | disable ] file
                          Disables shared library debugging of the adopted
                          process by clearing private data switches within
                          the file.

           pxdb -s  [ status ] file
                          This command reports whether: shared-library
                          debugging is enabled or disabled, symbolic-
                          debugging information is present, or symbolic-
                          debug information has already been preprocessed.
                          file is not changed when the status option is
                          given.  If all three conditions are true, an exit
                          value of 0 is returned; otherwise 1.

      Note that for the on or off options, file must be writable by the
      user.

 WARNINGS
      The debugger does not terminate on an interrupt (SIGINT); but jumps
      instead to its main loop and awaits another command.  However, this
      does not imply that sending the debugger an interrupt is harmless.  It
      can result in internal tables being left in an inconsistent state that
      could produce incorrect behavior.

      Code that is not compiled debuggable or does not have a corresponding
      source file is dealt with in a half-hearted manner.  The debugger
      shows unknown for unknown file and procedure names, cannot show code
      locations or interpret parameter lists, etc.  However, the linker
      symbol table provides procedure names for most procedures, even if
      they are not debuggable.

      On some systems, if the debugger is run on a shared objectfile you
      cannot set breakpoints.  (This may only apply if someone else is also
      executing the program.) This may be indicated by the error "Bad
      access" when you attempt to start a child process.  If another person
      starts running objectfile while you are debugging, they and you may
      have some interesting interactions.

      The debugger will probably be unusable on systems that have been
      booted from something other than /hp-ux (such as if SYSBCKUP was
      booted instead on a Series 300/400 system).

      The debugger has no knowledge about or control over child processes
      forked in turn by the process being debugged.  Programs being debugged
      should not execute a different program via exec() without a fork()
      (see exec(2) and fork(2)).



 Hewlett-Packard Company           - 17 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      Child process output may be (and usually is) buffered.  Hence it may
      not appear immediately after you step through an output statement such
      as printf() (see printf(3S)).  It may not appear at all if you kill
      the process.

      If the address given to a ba command is not a code address in the
      child process, meaningless results or errors may ensue.

      Single stepping floating-point instructions may show delayed results
      for operations that are actually emulated via exception traps (e.g.
      fsin on the Series 300/400 MC68040 processor).  Actual results will
      not be apparent until the next floating-point operation is performed.

      Debugging dynamically loaded code is inherently difficult, since no
      symbols within it are known to the debugger.

      If you set the address printing format to something printf(3S) does
      not like, you may get an error (usually memory fault) each time you
      try to print an address, until you fix the format with another f
      command.

      Do not use the z command to manipulate the SIGTRAP signal.  This
      signal is used by the debugger to synchronize with and control the
      traced process, and unpredictable results may occur if it is otherwise
      manipulated.  A corrolary to this is that applications that make use
      of the SIGTRAP signal are at best difficult to debug.

      If you single step or run with assertions through a call to longjmp()
      (see setjmp(3C)), the child process will probably take off free-
      running because the debugger sets, but never hits, an up-level
      breakpoint.

      Do not modify any file while the debugger has it open.  If you do, the
      debugger gets confused and may display garbage.

      Although the debugger tries to do things reasonably, it is possible to
      confuse the recording mechanism.  Be careful about trying to play back
      from a file currently open for recording, or vice versa; strange
      things can happen.

      The output of some program generators such as yacc have compiler-
      line-number directives in them that can confuse the debugger (see
      yacc(1)).  It expects source line entries in the symbol table to
      appear in sorted order.

 DEPENDENCIES
    Series 300/400
      The lc command is not supported on the Series 300 or 400.

    Series 700/800 (PA-RISC)
      All programs are shared executables.  This implies three limitations.



 Hewlett-Packard Company           - 18 -     HP-UX Release 9.0: August 1992






 xdb(1)                                                               xdb(1)




      You cannot set breakpoints or single step a program if another process
      is running it; the error message Bad access to child process results.
      If debugging a program, and another process starts to run the same
      program, either through your process executing a fork(), or another
      process, such as a shell, executing an exec(), this second process can
      hit one of your breakpoints and generate a SIGTRAP.  You cannot single
      step through a call to fork().

 AUTHOR
      xdb was developed by HP and Third Eye Software.

 FILES
      a.out                       Default objectfile to debug.
      core                        Default corefile to debug.
      /usr/lib/xdb.help           Text file listed by the help command.
      /usr/lib/xdb.help.nro       Unformatted text file used to generate
                                  xdb.help.
      /usr/lib/end.o              Auxiliary object file (support module) to
                                  link with all debuggable programs.
      /usr/lib/nls/$LANG/xdb.cat  The xdb message catalog.
      /usr/lib/nls/$LANG/pxdb.cat The pxdb message catalog.
      /usr/lib/xdb_demos/*        Demo files.
      $HOME/.xdbrc                The xdb startup command file.

 SEE ALSO
      adb(1), cc(1), echo(1), fc(1), ksh(1), ld(1), more(1), pc(1),
      creat(2), exec(2), fork(2), open(2), ptrace(2), ecvt(3C),
      multibyte(3C), printf(3S), setjmp(3C), shl_load(3X), system(3S),
      a.out(4), core(4), user(4), lang(5), signal(5).

      HP-UX Symbolic Debugger User's Guide
      HP-UX Symbolic Debugger Quick Reference.






















 Hewlett-Packard Company           - 19 -     HP-UX Release 9.0: August 1992



