home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / gdb.i01 < prev    next >
Encoding:
GNU Info File  |  1993-06-12  |  49.9 KB  |  1,274 lines
  1. This is Info file gdb.info, produced by Makeinfo-1.47 from the input
  2. file gdb-all.tex.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Gdb: (gdb).                   The GNU debugger.
  6. END-INFO-DIR-ENTRY
  7.    This file documents the GNU debugger GDB.
  8.  
  9.    This is Edition 4.06, October 1992, of `Debugging with GDB: the GNU
  10. Source-Level Debugger' for GDB Version 4.7.
  11.  
  12.    Copyright (C) 1988, 1989, 1990, 1991, 1992 Free Software Foundation,
  13. Inc.
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided also
  21. that the section entitled "GNU General Public License" is included
  22. exactly as in the original, and provided that the entire resulting
  23. derived work is distributed under the terms of a permission notice
  24. identical to this one.
  25.  
  26.    Permission is granted to copy and distribute translations of this
  27. manual into another language, under the above conditions for modified
  28. versions, except that the section entitled "GNU General Public License"
  29. may be included in a translation approved by the Free Software
  30. Foundation instead of in the original English.
  31.  
  32. 
  33. File: gdb.info,  Node: Top,  Next: Summary,  Prev: (DIR),  Up: (DIR)
  34.  
  35. Debugging with GDB
  36. ******************
  37.  
  38.    This file describes GDB, the GNU symbolic debugger.
  39.  
  40.    This is Edition 4.06, October 1992, for GDB Version 4.7.
  41.  
  42. * Menu:
  43.  
  44. * Summary::                     Summary of GDB
  45. * New Features::                New features since GDB version 3.5
  46. * Sample Session::              A sample GDB session
  47. * Invocation::                  Getting in and out of GDB
  48. * Commands::                    GDB commands
  49. * Running::                     Running programs under GDB
  50. * Stopping::                    Stopping and continuing
  51. * Stack::                       Examining the stack
  52. * Source::                      Examining source files
  53. * Data::                        Examining data
  54. * Languages::                   Using GDB with different languages
  55. * Symbols::                     Examining the symbol table
  56. * Altering::                    Altering execution
  57. * GDB Files::                   GDB's files
  58. * Targets::                     Specifying a debugging target
  59. * Controlling GDB::             Controlling GDB
  60. * Sequences::                   Canned sequences of commands
  61. * Emacs::                       Using GDB under GNU Emacs
  62. * GDB Bugs::                    Reporting bugs in GDB
  63. * Renamed Commands::
  64. * Formatting Documentation::    How to format and print GDB documentation
  65. * Installing GDB::              Installing GDB
  66. * Copying::                     GNU GENERAL PUBLIC LICENSE
  67. * Index::                       Index
  68.  
  69. 
  70. File: gdb.info,  Node: Summary,  Next: New Features,  Prev: Top,  Up: Top
  71.  
  72. Summary of GDB
  73. **************
  74.  
  75.    The purpose of a debugger such as GDB is to allow you to see what is
  76. going on "inside" another program while it executes--or what another
  77. program was doing at the moment it crashed.
  78.  
  79.    GDB can do four main kinds of things (plus other things in support of
  80. these) to help you catch bugs in the act:
  81.  
  82.    * Start your program, specifying anything that might affect its
  83.      behavior.
  84.  
  85.    * Make your program stop on specified conditions.
  86.  
  87.    * Examine what has happened, when your program has stopped.
  88.  
  89.    * Change things in your program, so you can experiment with
  90.      correcting the effects of one bug and go on to learn about another.
  91.  
  92.    You can use GDB to debug programs written in C, C++, and Modula-2.
  93. Fortran support will be added when a GNU Fortran compiler is ready.
  94.  
  95. * Menu:
  96.  
  97. * Free Software::               Free Software
  98. * Contributors::                Contributors to GDB
  99.  
  100. 
  101. File: gdb.info,  Node: Free Software,  Next: Contributors,  Up: Summary
  102.  
  103. Free Software
  104. =============
  105.  
  106.    GDB is "free software", protected by the GNU General Public License
  107. (GPL).  The GPL gives you the freedom to copy or adapt a licensed
  108. program--but every person getting a copy also gets with it the freedom
  109. to modify that copy (which means that they must get access to the
  110. source code), and the freedom to distribute further copies. Typical
  111. software companies use copyrights to limit your freedoms; the Free
  112. Software Foundation uses the GPL to preserve these freedoms.
  113.  
  114.    Fundamentally, the General Public License is a license which says
  115. that you have these freedoms and that you cannot take these freedoms
  116. away from anyone else.
  117.  
  118.    For full details, *note GNU GENERAL PUBLIC LICENSE: Copying..
  119.  
  120. 
  121. File: gdb.info,  Node: Contributors,  Prev: Free Software,  Up: Summary
  122.  
  123. Contributors to GDB
  124. ===================
  125.  
  126.    Richard Stallman was the original author of GDB, and of many other
  127. GNU programs.  Many others have contributed to its development.  This
  128. section attempts to credit major contributors.  One of the virtues of
  129. free software is that everyone is free to contribute to it; with
  130. regret, we cannot actually acknowledge everyone here.  The file
  131. `ChangeLog' in the GDB distribution approximates a blow-by-blow account.
  132.  
  133.    Changes much prior to version 2.0 are lost in the mists of time.
  134.  
  135.      *Plea:* Additions to this section are particularly welcome.  If you
  136.      or your friends (or enemies; let's be evenhanded) have been
  137.      unfairly omitted from this list, we would like to add your names!
  138.  
  139.    So that they may not regard their long labor as thankless, we
  140. particularly thank those who shepherded GDB through major releases: Stu
  141. Grossman and John Gilmore (releases 4.6, 4.5, 4.4), John Gilmore
  142. (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases 3.5, 3.4,
  143. 3.3); and Randy Smith (releases 3.2, 3.1, 3.0).  As major maintainer of
  144. GDB for some period, each contributed significantly to the structure,
  145. stability, and capabilities of the entire debugger.
  146.  
  147.    Richard Stallman, assisted at various times by Pete TerMaat, Chris
  148. Hanson, and Richard Mlynarik, handled releases through 2.8.
  149.  
  150.    Michael Tiemann is the author of most of the GNU C++ support in GDB,
  151. with significant additional contributions from Per Bothner.  James
  152. Clark wrote the GNU C++ demangler.  Early work on C++ was by Peter
  153. TerMaat (who also did much general update work leading to release 3.0).
  154.  
  155.    GDB 4 uses the BFD subroutine library to examine multiple
  156. object-file formats; BFD was a joint project of David V.
  157. Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
  158.  
  159.    David Johnson wrote the original COFF support; Pace Willison did the
  160. original support for encapsulated COFF.
  161.  
  162.    Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
  163. Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
  164. support.  Jean-Daniel Fekete contributed Sun 386i support.  Chris
  165. Hanson improved the HP9000 support.  Noboyuki Hikichi and Tomoyuki
  166. Hasei contributed Sony/News OS 3 support.  David Johnson contributed
  167. Encore Umax support.  Jyrki Kuoppala contributed Altos 3068 support.
  168. Keith Packard contributed NS32K support.  Doug Rabson contributed Acorn
  169. Risc Machine support.  Chris Smith contributed Convex support (and
  170. Fortran debugging).  Jonathan Stone contributed Pyramid support.
  171. Michael Tiemann contributed SPARC support.  Tim Tucker contributed
  172. support for the Gould NP1 and Gould Powernode.  Pace Willison
  173. contributed Intel 386 support.  Jay Vosburgh contributed Symmetry
  174. support.
  175.  
  176.    Rich Schaefer and Peter Schauer helped with support of SunOS shared
  177. libraries.
  178.  
  179.    Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
  180. several machine instruction sets.
  181.  
  182.    Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
  183. develop remote debugging.  Intel Corporation and Wind River Systems
  184. contributed remote debugging modules for their products.
  185.  
  186.    Brian Fox is the author of the readline libraries providing
  187. command-line editing and command history.
  188.  
  189.    Andrew Beers of SUNY Buffalo wrote the language-switching code and
  190. the Modula-2 support, and contributed the Languages chapter of this
  191. manual.
  192.  
  193.    Fred Fish wrote most of the support for Unix System Vr4, and enhanced
  194. the command-completion support to cover C++ overloaded symbols.
  195.  
  196. 
  197. File: gdb.info,  Node: New Features,  Next: Sample Session,  Prev: Summary,  Up: Top
  198.  
  199. New Features since GDB version 3.5
  200. **********************************
  201.  
  202. *Targets*
  203.      Using the new command `target', you can select at runtime whether
  204.      you are debugging local files, local processes, standalone systems
  205.      over a serial port, realtime systems over a TCP/IP connection,
  206.      etc.  The command `load' can download programs into a remote
  207.      system.  Serial stubs are available for Motorola 680x0, Intel
  208.      80386, and Sparc remote systems; GDB also supports debugging
  209.      realtime processes running under VxWorks, using SunRPC Remote
  210.      Procedure Calls over TCP/IP to talk to a debugger stub on the
  211.      target system.  Internally, GDB now uses a function vector to
  212.      mediate access to different targets; if you need to add your own
  213.      support for a remote protocol, this makes it much easier.
  214.  
  215. *Watchpoints*
  216.      GDB now sports watchpoints as well as breakpoints.  You can use a
  217.      watchpoint to stop execution whenever the value of an expression
  218.      changes, without having to predict a particular place in your
  219.      program where this may happen.
  220.  
  221. *Wide Output*
  222.      Commands that issue wide output now insert newlines at places
  223.      designed to make the output more readable.
  224.  
  225. *Object Code Formats*
  226.      GDB uses a new library called the Binary File Descriptor (BFD)
  227.      Library to permit it to switch dynamically, without
  228.      reconfiguration or recompilation, between different object-file
  229.      formats.  Formats currently supported are COFF, a.out, and the
  230.      Intel 960 b.out; files may be read as .o's, archive libraries, or
  231.      core dumps.  BFD is available as a subroutine library so that
  232.      other programs may take advantage of it, and the other GNU binary
  233.      utilities are being converted to use it.
  234.  
  235. *Configuration and Ports*
  236.      Compile-time configuration (to select a particular architecture and
  237.      operating system) is much easier.  The script `configure' now
  238.      allows you to configure GDB as either a native debugger or a
  239.      cross-debugger. *Note Installing GDB::, for details on how to
  240.      configure.
  241.  
  242. *Interaction*
  243.      The user interface to GDB's control variables has been simplified
  244.      and consolidated in two commands, `set' and `show'.  Output lines
  245.      are now broken at readable places, rather than overflowing onto
  246.      the next line.  You can suppress output of machine-level addresses,
  247.      displaying only source language information.
  248.  
  249. *C++*
  250.      GDB now supports C++ multiple inheritance (if used with a GCC
  251.      version 2 compiler), and also has limited support for C++ exception
  252.      handling, with the commands `catch' and `info catch': GDB can
  253.      break when an exception is raised, before the stack is peeled back
  254.      to the exception handler's context.
  255.  
  256. *Modula-2*
  257.      GDB now has preliminary support for the GNU Modula-2 compiler,
  258.      currently under development at the State University of New York at
  259.      Buffalo.  Coordinated development of both GDB and the GNU Modula-2
  260.      compiler will continue into 1992.  Other Modula-2 compilers are
  261.      currently not supported, and attempting to debug programs compiled
  262.      with them will likely result in an error as the symbol table of the
  263.      executable is read in.
  264.  
  265. *Command Rationalization*
  266.      Many GDB commands have been renamed to make them easier to remember
  267.      and use.  In particular, the subcommands of `info' and
  268.      `show'/`set' are grouped to make the former refer to the state of
  269.      your program, and the latter refer to the state of GDB itself.
  270.      *Note Renamed Commands::, for details on what commands were
  271.      renamed.
  272.  
  273. *Shared Libraries*
  274.      GDB 4 can debug programs and core files that use SunOS, SVR4, or
  275.      IBM RS/6000 shared libraries.
  276.  
  277. *Reference Card*
  278.      GDB 4 has a reference card.  *Note Formatting the Documentation:
  279.      Formatting Documentation, for instructions to print it.
  280.  
  281. *Work in Progress*
  282.      Kernel debugging for BSD and Mach systems; Tahoe and HPPA
  283.      architecture support.
  284.  
  285. 
  286. File: gdb.info,  Node: Sample Session,  Next: Invocation,  Prev: New Features,  Up: Top
  287.  
  288. A Sample GDB Session
  289. ********************
  290.  
  291.    You can use this manual at your leisure to read all about GDB.
  292. However, a handful of commands are enough to get started using the
  293. debugger.  This chapter illustrates these commands.
  294.  
  295.    One of the preliminary versions of GNU `m4' (a generic macro
  296. processor) exhibits the following bug: sometimes, when we change its
  297. quote strings from the default, the commands used to capture one macro's
  298. definition in another stop working.  In the following short `m4'
  299. session, we define a macro `foo' which expands to `0000'; we then use
  300. the `m4' built-in `defn' to define `bar' as the same thing.  However,
  301. when we change the open quote string to `<QUOTE>' and the close quote
  302. string to `<UNQUOTE>', the same procedure fails to define a new synonym
  303. `baz':
  304.  
  305.      $ cd gnu/m4
  306.      $ ./m4
  307.      define(foo,0000)
  308.      
  309.      foo
  310.      0000
  311.      define(bar,defn(`foo'))
  312.      
  313.      bar
  314.      0000
  315.      changequote(<QUOTE>,<UNQUOTE>)
  316.      
  317.      define(baz,defn(<QUOTE>foo<UNQUOTE>))
  318.      baz
  319.      C-d
  320.      m4: End of input: 0: fatal error: EOF in string
  321.  
  322. Let's use GDB to try to see what's going on.
  323.  
  324.      $ gdb m4
  325.      GDB is free software and you are welcome to distribute copies
  326.       of it under certain conditions; type "show copying" to see
  327.       the conditions.
  328.      There is absolutely no warranty for GDB; type "show warranty"
  329.      for details.
  330.      GDB 4.7, Copyright 1992 Free Software Foundation, Inc...
  331.      (gdb)
  332.  
  333. GDB reads only enough symbol data to know where to find the rest when
  334. needed; as a result, the first prompt comes up very quickly.  We now
  335. tell GDB to use a narrower display width than usual, so that examples
  336. will fit in this manual.
  337.  
  338.      (gdb) set width 70
  339.  
  340. Let's see how the `m4' built-in `changequote' works. Having looked at
  341. the source, we know the relevant subroutine is `m4_changequote', so we
  342. set a breakpoint there with GDB's `break' command.
  343.  
  344.      (gdb) break m4_changequote
  345.      Breakpoint 1 at 0x62f4: file builtin.c, line 879.
  346.  
  347. Using the `run' command, we start `m4' running under GDB control; as
  348. long as control does not reach the `m4_changequote' subroutine, the
  349. program runs as usual:
  350.  
  351.      (gdb) run
  352.      Starting program: /work/Editorial/gdb/gnu/m4/m4
  353.      define(foo,0000)
  354.      
  355.      foo
  356.      0000
  357.  
  358. To trigger the breakpoint, we call `changequote'.  GDB suspends
  359. execution of `m4', displaying information about the context where it
  360. stops.
  361.  
  362.      changequote(<QUOTE>,<UNQUOTE>)
  363.      
  364.      Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
  365.          at builtin.c:879
  366.      879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
  367.  
  368. Now we use the command `n' (`next') to advance execution to the next
  369. line of the current function.
  370.  
  371.      (gdb) n
  372.      882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
  373.       : nil,
  374.  
  375. `set_quotes' looks like a promising subroutine.  We can go into it by
  376. using the command `s' (`step') instead of `next'. `step' goes to the
  377. next line to be executed in *any* subroutine, so it steps into
  378. `set_quotes'.
  379.  
  380.      (gdb) s
  381.      set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
  382.          at input.c:530
  383.      530         if (lquote != def_lquote)
  384.  
  385. The display that shows the subroutine where `m4' is now suspended (and
  386. its arguments) is called a stack frame display.  It shows a summary of
  387. the stack.  We can use the `backtrace' command (which can also be
  388. spelled `bt'), to see where we are in the stack as a whole: the
  389. `backtrace' command displays a stack frame for each active subroutine.
  390.  
  391.      (gdb) bt
  392.      #0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
  393.          at input.c:530
  394.      #1  0x6344 in m4_changequote (argc=3, argv=0x33c70)
  395.          at builtin.c:882
  396.      #2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
  397.      #3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
  398.          at macro.c:71
  399.      #4  0x79dc in expand_input () at macro.c:40
  400.      #5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
  401.  
  402. Let's step through a few more lines to see what happens.  The first two
  403. times, we can use `s'; the next two times we use `n' to avoid falling
  404. into the `xstrdup' subroutine.
  405.  
  406.      (gdb) s
  407.      0x3b5c  532         if (rquote != def_rquote)
  408.      (gdb) s
  409.      0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \
  410.      def_lquote : xstrdup(lq);
  411.      (gdb) n
  412.      536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
  413.       : xstrdup(rq);
  414.      (gdb) n
  415.      538         len_lquote = strlen(rquote);
  416.  
  417. The last line displayed looks a little odd; let's examine the variables
  418. `lquote' and `rquote' to see if they are in fact the new left and right
  419. quotes we specified.  We can use the command `p' (`print') to see their
  420. values.
  421.  
  422.      (gdb) p lquote
  423.      $1 = 0x35d40 "<QUOTE>"
  424.      (gdb) p rquote
  425.      $2 = 0x35d50 "<UNQUOTE>"
  426.  
  427. `lquote' and `rquote' are indeed the new left and right quotes. Let's
  428. look at some context; we can display ten lines of source surrounding
  429. the current line, with the `l' (`list') command.
  430.  
  431.      (gdb) l
  432.      533             xfree(rquote);
  433.      534
  434.      535         lquote = (lq == nil || *lq == '\0') ? def_lquote\
  435.       : xstrdup (lq);
  436.      536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
  437.       : xstrdup (rq);
  438.      537
  439.      538         len_lquote = strlen(rquote);
  440.      539         len_rquote = strlen(lquote);
  441.      540     }
  442.      541
  443.      542     void
  444.  
  445. Let's step past the two lines that set `len_lquote' and `len_rquote',
  446. and then examine the values of those variables.
  447.  
  448.      (gdb) n
  449.      539         len_rquote = strlen(lquote);
  450.      (gdb) n
  451.      540     }
  452.      (gdb) p len_lquote
  453.      $3 = 9
  454.      (gdb) p len_rquote
  455.      $4 = 7
  456.  
  457. That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
  458. meant to be the lengths of `lquote' and `rquote' respectively.  Let's
  459. try setting them to better values. We can use the `p' command for this,
  460. since it'll print the value of any expression--and that expression can
  461. include subroutine calls and assignments.
  462.  
  463.      (gdb) p len_lquote=strlen(lquote)
  464.      $5 = 7
  465.      (gdb) p len_rquote=strlen(rquote)
  466.      $6 = 9
  467.  
  468. Let's see if that fixes the problem of using the new quotes with the
  469. `m4' built-in `defn'.  We can allow `m4' to continue executing with the
  470. `c' (`continue') command, and then try the example that caused trouble
  471. initially:
  472.  
  473.      (gdb) c
  474.      Continuing.
  475.      
  476.      define(baz,defn(<QUOTE>foo<UNQUOTE>))
  477.      
  478.      baz
  479.      0000
  480.  
  481. Success!  The new quotes now work just as well as the default ones.  The
  482. problem seems to have been just the two typos defining the wrong
  483. lengths.  We'll let `m4' exit by giving it an EOF as input.
  484.  
  485.      C-d
  486.      Program exited normally.
  487.  
  488. The message `Program exited normally.' is from GDB; it indicates `m4'
  489. has finished executing.  We can end our GDB session with the GDB `quit'
  490. command.
  491.  
  492.      (gdb) quit
  493.  
  494. 
  495. File: gdb.info,  Node: Invocation,  Next: Commands,  Prev: Sample Session,  Up: Top
  496.  
  497. Getting In and Out of GDB
  498. *************************
  499.  
  500.    This chapter discusses how to start GDB, and how to get out of it.
  501. (The essentials: type `gdb' to start GDB, and type `quit' or `C-d' to
  502. exit.)
  503.  
  504. * Menu:
  505.  
  506. * Invoking GDB::                Starting GDB
  507. * Leaving GDB::                 Leaving GDB
  508. * Shell Commands::              Shell Commands
  509.  
  510. 
  511. File: gdb.info,  Node: Invoking GDB,  Next: Leaving GDB,  Up: Invocation
  512.  
  513. Starting GDB
  514. ============
  515.  
  516.    For details on starting up gdb as a remote debugger attached to a
  517. Hitachi H8/300 board, see *Note GDB and the Hitachi H8/300: Hitachi
  518. H8/300 Remote.
  519.  
  520.    Start GDB by running the program `gdb'.  Once it's running, GDB
  521. reads commands from the terminal until you tell it to exit.
  522.  
  523.    You can also run `gdb' with a variety of arguments and options, to
  524. specify more of your debugging environment at the outset.
  525.  
  526.    The command-line options described here are designed to cover a
  527. variety of situations; in some environments, some of these options may
  528. effectively be unavailable.
  529.  
  530.    The most usual way to start GDB is with one argument, specifying an
  531. executable program:
  532.  
  533.      gdb PROGRAM
  534.  
  535. You can also start with both an executable program and a core file
  536. specified:
  537.  
  538.      gdb PROGRAM CORE
  539.  
  540.    You can, instead, specify a process ID as a second argument, if you
  541. want to debug a running process:
  542.  
  543.      gdb PROGRAM 1234
  544.  
  545. would attach GDB to process `1234' (unless you also have a file named
  546. `1234'; GDB does check for a core file first).
  547.  
  548.    Taking advantage of the second command-line argument requires a
  549. fairly complete operating system; when you use GDB as a remote debugger
  550. attached to a bare board, there may not be any notion of "process", and
  551. there is often no way to get a core dump.
  552.  
  553. You can further control how GDB starts up by using command-line
  554. options.  GDB itself can remind you of the options available.
  555.  
  556. Type
  557.  
  558.      gdb -help
  559.  
  560. to display all available options and briefly describe their use (`gdb
  561. -h' is a shorter equivalent).
  562.  
  563.    All options and command line arguments you give are processed in
  564. sequential order.  The order makes a difference when the `-x' option is
  565. used.
  566.  
  567. * Menu:
  568.  
  569. * File Options::                Choosing Files
  570. * Mode Options::                Choosing Modes
  571.  
  572. 
  573. File: gdb.info,  Node: File Options,  Next: Mode Options,  Up: Invoking GDB
  574.  
  575. Choosing Files
  576. --------------
  577.  
  578.    When GDB starts, it reads any arguments other than options as
  579. specifying an executable file and core file (or process ID).  This is
  580. the same as if the arguments were specified by the `-se' and `-c'
  581. options respectively.  (GDB reads the first argument that does not have
  582. an associated option flag as equivalent to the `-se' option followed by
  583. that argument; and the second argument that does not have an associated
  584. option flag, if any, as equivalent to the `-c' option followed by that
  585. argument.)
  586.  
  587.    Many options have both long and short forms; both are shown in the
  588. following list.  GDB also recognizes the long forms if you truncate
  589. them, so long as enough of the option is present to be unambiguous. (If
  590. you prefer, you can flag option arguments with `--' rather than `-',
  591. though we illustrate the more usual convention.)
  592.  
  593. `-symbols=FILE'
  594. `-s FILE'
  595.      Read symbol table from file FILE.
  596.  
  597. `-exec=FILE'
  598. `-e FILE'
  599.      Use file FILE as the executable file to execute when appropriate,
  600.      and for examining pure data in conjunction with a core dump.
  601.  
  602. `-se=FILE'
  603.      Read symbol table from file FILE and use it as the executable file.
  604.  
  605. `-core=FILE'
  606. `-c FILE'
  607.      Use file FILE as a core dump to examine.
  608.  
  609. `-command=FILE'
  610. `-x FILE'
  611.      Execute GDB commands from file FILE.  *Note Command Files::.
  612.  
  613. `-directory=DIRECTORY'
  614. `-d DIRECTORY'
  615.      Add DIRECTORY to the path to search for source files.
  616.  
  617. `-m'
  618. `-mapped'
  619.      *Warning: this option depends on operating system facilities that
  620.      are not supported on all systems.*
  621.      If memory-mapped files are available on your system through the
  622.      `mmap' system call, you can use this option to have GDB write the
  623.      symbols from your program into a reusable file in the current
  624.      directory.  If the program you are debugging is called
  625.      `/tmp/fred', the mapped symbol file will be `./fred.syms'. Future
  626.      GDB debugging sessions will notice the presence of this file, and
  627.      will quickly map in symbol information from it, rather than reading
  628.      the symbol table from the executable program.
  629.  
  630.      The `.syms' file is specific to the host machine on which GDB is
  631.      run. It holds an exact image of GDB's internal symbol table.  It
  632.      cannot be shared across multiple host platforms.
  633.  
  634. `-r'
  635. `-readnow'
  636.      Read each symbol file's entire symbol table immediately, rather
  637.      than the default, which is to read it incrementally as it is
  638.      needed. This makes startup slower, but makes future operations
  639.      faster.
  640.  
  641.    The `-mapped' and `-readnow' options are typically combined in order
  642. to build a `.syms' file that contains complete symbol information. A
  643. simple GDB invocation to do nothing but build a `.syms' file for future
  644. use is:
  645.  
  646.          gdb -batch -nx -mapped -readnow programname
  647.  
  648. 
  649. File: gdb.info,  Node: Mode Options,  Prev: File Options,  Up: Invoking GDB
  650.  
  651. Choosing Modes
  652. --------------
  653.  
  654.    You can run GDB in various alternative modes--for example, in batch
  655. mode or quiet mode.
  656.  
  657. `-nx'
  658. `-n'
  659.      Do not execute commands from any `.gdbinit' initialization files.
  660.      Normally, the commands in these files are executed after all the
  661.      command options and arguments have been processed. *Note Command
  662.      Files::.
  663.  
  664. `-quiet'
  665. `-q'
  666.      "Quiet".  Do not print the introductory and copyright messages. 
  667.      These messages are also suppressed in batch mode.
  668.  
  669. `-batch'
  670.      Run in batch mode.  Exit with status `0' after processing all the
  671.      command files specified with `-x' (and `.gdbinit', if not
  672.      inhibited). Exit with nonzero status if an error occurs in
  673.      executing the GDB commands in the command files.
  674.  
  675.      Batch mode may be useful for running GDB as a filter, for example
  676.      to download and run a program on another computer; in order to
  677.      make this more useful, the message
  678.  
  679.           Program exited normally.
  680.  
  681.      (which is ordinarily issued whenever a program running under GDB
  682.      control terminates) is not issued when running in batch mode.
  683.  
  684. `-cd=DIRECTORY'
  685.      Run GDB using DIRECTORY as its working directory, instead of the
  686.      current directory.
  687.  
  688. `-fullname'
  689. `-f'
  690.      Emacs sets this option when it runs GDB as a subprocess.  It tells
  691.      GDB to output the full file name and line number in a standard,
  692.      recognizable fashion each time a stack frame is displayed (which
  693.      includes each time your program stops).  This recognizable format
  694.      looks like two `\032' characters, followed by the file name, line
  695.      number and character position separated by colons, and a newline. 
  696.      The Emacs-to-GDB interface program uses the two `\032' characters
  697.      as a signal to display the source code for the frame.
  698.  
  699. `-b BPS'
  700.      Set the line speed (baud rate or bits per second) of any serial
  701.      interface used by GDB for remote debugging.
  702.  
  703. `-tty=DEVICE'
  704.      Run using DEVICE for your program's standard input and output.
  705.  
  706. 
  707. File: gdb.info,  Node: Leaving GDB,  Next: Shell Commands,  Prev: Invoking GDB,  Up: Invocation
  708.  
  709. Leaving GDB
  710. ===========
  711.  
  712. `quit'
  713.      To exit GDB, use the `quit' command (abbreviated `q'), or type an
  714.      end-of-file character (usually `C-d').
  715.  
  716.    An interrupt (often `C-c') will not exit from GDB, but rather will
  717. terminate the action of any GDB command that is in progress and return
  718. to GDB command level.  It is safe to type the interrupt character at
  719. any time because GDB does not allow it to take effect until a time when
  720. it is safe.
  721.  
  722.    If you have been using GDB to control an attached process or device,
  723. you can release it with the `detach' command; *note Debugging an
  724. Already-Running Process: Attach...
  725.  
  726. 
  727. File: gdb.info,  Node: Shell Commands,  Prev: Leaving GDB,  Up: Invocation
  728.  
  729. Shell Commands
  730. ==============
  731.  
  732.    If you need to execute occasional shell commands during your
  733. debugging session, there is no need to leave or suspend GDB; you can
  734. just use the `shell' command.
  735.  
  736. `shell COMMAND STRING'
  737.      Directs GDB to invoke an inferior shell to execute COMMAND STRING.
  738.       If it exists, the environment variable `SHELL' is used for the
  739.      name of the shell to run.  Otherwise GDB uses `/bin/sh'.
  740.  
  741.    The utility `make' is often needed in development environments. You
  742. do not have to use the `shell' command for this purpose in GDB:
  743.  
  744. `make MAKE-ARGS'
  745.      Causes GDB to execute an inferior `make' program with the specified
  746.      arguments.  This is equivalent to `shell make MAKE-ARGS'.
  747.  
  748. 
  749. File: gdb.info,  Node: Commands,  Next: Running,  Prev: Invocation,  Up: Top
  750.  
  751. GDB Commands
  752. ************
  753.  
  754.    You can abbreviate a GDB command to the first few letters of the
  755. command name, if that abbreviation is unambiguous; and you can repeat
  756. certain GDB commands by typing just RET.  You can also use the TAB key
  757. to get GDB to fill out the rest of a word in a command (or to show you
  758. the alternatives available, if there's more than one possibility).
  759.  
  760. * Menu:
  761.  
  762. * Command Syntax::              Command Syntax
  763. * Completion::                  Command Completion
  764. * Help::                        Getting Help
  765.  
  766. 
  767. File: gdb.info,  Node: Command Syntax,  Next: Completion,  Up: Commands
  768.  
  769. Command Syntax
  770. ==============
  771.  
  772.    A GDB command is a single line of input.  There is no limit on how
  773. long it can be.  It starts with a command name, which is followed by
  774. arguments whose meaning depends on the command name.  For example, the
  775. command `step' accepts an argument which is the number of times to step,
  776. as in `step 5'.  You can also use the `step' command with no arguments.
  777.  Some command names do not allow any arguments.
  778.  
  779.    GDB command names may always be truncated if that abbreviation is
  780. unambiguous.  Other possible command abbreviations are listed in the
  781. documentation for individual commands.  In some cases, even ambiguous
  782. abbreviations are allowed; for example, `s' is specially defined as
  783. equivalent to `step' even though there are other commands whose names
  784. start with `s'.  You can test abbreviations by using them as arguments
  785. to the `help' command.
  786.  
  787.    A blank line as input to GDB (typing just RET) means to repeat the
  788. previous command. Certain commands (for example, `run') will not repeat
  789. this way; these are commands for which unintentional repetition might
  790. cause trouble and which you are unlikely to want to repeat.
  791.  
  792.    The `list' and `x' commands, when you repeat them with RET,
  793. construct new arguments rather than repeating exactly as typed.  This
  794. permits easy scanning of source or memory.
  795.  
  796.    GDB can also use RET in another way: to partition lengthy output, in
  797. a way similar to the common utility `more' (*note Screen Size::.). 
  798. Since it is easy to press one RET too many in this situation, GDB
  799. disables command repetition after any command that generates this sort
  800. of display.
  801.  
  802.    A line of input starting with `#' is a comment; it does nothing.
  803. This is useful mainly in command files (*note Command Files::.).
  804.  
  805. 
  806. File: gdb.info,  Node: Completion,  Next: Help,  Prev: Command Syntax,  Up: Commands
  807.  
  808. Command Completion
  809. ==================
  810.  
  811.    GDB can fill in the rest of a word in a command for you, if there's
  812. only one possibility; it can also show you what the valid possibilities
  813. are for the next word in a command, at any time.  This works for GDB
  814. commands, GDB subcommands, and the names of symbols in your program.
  815.  
  816.    Press the TAB key whenever you want GDB to fill out the rest of a
  817. word.  If there's only one possibility, GDB will fill in the word, and
  818. wait for you to finish the command (or press RET to enter it).  For
  819. example, if you type
  820.  
  821.      (gdb) info bre TAB
  822.  
  823. GDB fills in the rest of the word `breakpoints', since that's the only
  824. `info' subcommand beginning with `bre':
  825.  
  826.      (gdb) info breakpoints
  827.  
  828. You can either press RET at this point, to run the `info breakpoints'
  829. command, or backspace and enter something else, if `breakpoints'
  830. doesn't look like the command you expected.  (If you were sure you
  831. wanted `info breakpoints' in the first place, you might as well just
  832. type RET immediately after `info bre', to exploit command abbreviations
  833. rather than command completion).
  834.  
  835.    If there is more than one possibility for the next word when you
  836. press TAB, GDB will sound a bell.  You can either supply more
  837. characters and try again, or just press TAB a second time, and GDB will
  838. display all the possible completions for that word.  For example, you
  839. might want to set a breakpoint on a subroutine whose name begins with
  840. `make_', but when you type `b make_TAB' GDB just sounds the bell. 
  841. Typing TAB again will display all the function names in your program
  842. that begin with those characters, for example:
  843.  
  844.      (gdb) b make_ TAB
  845. GDB sounds bell; press TAB again, to see:
  846.      make_a_section_from_file     make_environ
  847.      make_abs_section             make_function_type
  848.      make_blockvector             make_pointer_type
  849.      make_cleanup                 make_reference_type
  850.      make_command                 make_symbol_completion_list
  851.      (GDBP__) b make_
  852.  
  853. After displaying the available possibilities, GDB copies your partial
  854. input (`b make_' in the example) so you can finish the command.
  855.  
  856.    If you just want to see the list of alternatives in the first place,
  857. you can press `M-?' rather than pressing TAB twice. `M-?' means `META
  858. ?'.  You can type this either by holding down a key designated as the
  859. META shift on your keyboard (if there is one) while typing `?', or as
  860. ESC followed by `?'.
  861.  
  862.    Sometimes the string you need, while logically a "word", may contain
  863. parentheses or other characters that GDB normally excludes from its
  864. notion of a word.  To permit word completion to work in this situation,
  865. you may enclose words in `'' (single quote marks) in GDB commands.
  866.  
  867.    The most likely situation where you might need this is in typing the
  868. name of a C++ function.  This is because C++ allows function overloading
  869. (multiple definitions of the same function, distinguished by argument
  870. type).  For example, when you want to set a breakpoint you may need to
  871. distinguish whether you mean the version of `name' that takes an `int'
  872. parameter, `name(int)', or the version that takes a `float' parameter,
  873. `name(float)'.  To use the word-completion facilities in this
  874. situation, type a single quote `'' at the beginning of the function
  875. name.  This alerts GDB that it may need to consider more information
  876. than usual when you press TAB or `M-?' to request word completion:
  877.  
  878.      (gdb) b 'bubble( M-?
  879.      bubble(double,double)    bubble(int,int)
  880.      (gdb) b 'bubble(
  881.  
  882.    In some cases, GDB can tell that completing a name will require
  883. quotes.  When this happens, GDB will insert the quote for you (while
  884. completing as much as it can) if you do not type the quote in the first
  885. place:
  886.  
  887.      (gdb) b bub TAB
  888. GDB alters your input line to the following, and rings a bell:
  889.      (gdb) b 'bubble(
  890.  
  891. In general, GDB can tell that a quote is needed (and inserts it) if you
  892. have not yet started typing the argument list when you ask for
  893. completion on an overloaded symbol.
  894.  
  895. 
  896. File: gdb.info,  Node: Help,  Prev: Completion,  Up: Commands
  897.  
  898. Getting Help
  899. ============
  900.  
  901.    You can always ask GDB itself for information on its commands, using
  902. the command `help'.
  903.  
  904. `help'
  905. `h'
  906.      You can use `help' (abbreviated `h') with no arguments to display
  907.      a short list of named classes of commands:
  908.  
  909.           (gdb) help
  910.           List of classes of commands:
  911.           
  912.           running -- Running the program
  913.           stack -- Examining the stack
  914.           data -- Examining data
  915.           breakpoints -- Making program stop at certain points
  916.           files -- Specifying and examining files
  917.           status -- Status inquiries
  918.           support -- Support facilities
  919.           user-defined -- User-defined commands
  920.           aliases -- Aliases of other commands
  921.           obscure -- Obscure features
  922.           
  923.           Type "help" followed by a class name for a list of
  924.           commands in that class.
  925.           Type "help" followed by command name for full
  926.           documentation.
  927.           Command name abbreviations are allowed if unambiguous.
  928.           (gdb)
  929.  
  930. `help CLASS'
  931.      Using one of the general help classes as an argument, you can get a
  932.      list of the individual commands in that class.  For example, here
  933.      is the help display for the class `status':
  934.  
  935.           (gdb) help status
  936.           Status inquiries.
  937.           
  938.           List of commands:
  939.           
  940.           show -- Generic command for showing things set with "set"
  941.           info -- Generic command for printing status
  942.           
  943.           Type "help" followed by command name for full
  944.           documentation.
  945.           Command name abbreviations are allowed if unambiguous.
  946.           (gdb)
  947.  
  948. `help COMMAND'
  949.      With a command name as `help' argument, GDB will display a short
  950.      paragraph on how to use that command.
  951.  
  952.    In addition to `help', you can use the GDB commands `info' and
  953. `show' to inquire about the state of your program, or the state of GDB
  954. itself.  Each command supports many topics of inquiry; this manual
  955. introduces each of them in the appropriate context.  The listings under
  956. `info' and under `show' in the Index point to all the sub-commands. 
  957. *Note Index::.
  958.  
  959. `info'
  960.      This command (abbreviated `i') is for describing the state of your
  961.      program; for example, it can list the arguments given to your
  962.      program (`info args'), the registers currently in use (`info
  963.      registers'), or the breakpoints you have set (`info breakpoints').
  964.      You can get a complete list of the `info' sub-commands with
  965.      `help info'.
  966.  
  967. `show'
  968.      In contrast, `show' is for describing the state of GDB itself. You
  969.      can change most of the things you can `show', by using the related
  970.      command `set'; for example, you can control what number system is
  971.      used for displays with `set radix', or simply inquire which is
  972.      currently in use with `show radix'.
  973.  
  974.      To display all the settable parameters and their current values,
  975.      you can use `show' with no arguments; you may also use `info set'.
  976.       Both commands produce the same display.
  977.  
  978.    Here are three miscellaneous `show' subcommands, all of which are
  979. exceptional in lacking corresponding `set' commands:
  980.  
  981. `show version'
  982.      Show what version of GDB is running.  You should include this
  983.      information in GDB bug-reports.  If multiple versions of GDB are in
  984.      use at your site, you may occasionally want to make sure what
  985.      version of GDB you are running; as GDB evolves, new commands are
  986.      introduced, and old ones may wither away.  The version number is
  987.      also announced when you start GDB with no arguments.
  988.  
  989. `show copying'
  990.      Display information about permission for copying GDB.
  991.  
  992. `show warranty'
  993.      Display the GNU "NO WARRANTY" statement.
  994.  
  995. 
  996. File: gdb.info,  Node: Running,  Next: Stopping,  Prev: Commands,  Up: Top
  997.  
  998. Running Programs Under GDB
  999. **************************
  1000.  
  1001.    To debug a program, you must run it under GDB.
  1002.  
  1003. * Menu:
  1004.  
  1005. * Compilation::                 Compiling for Debugging
  1006. * Starting::                    Starting your Program
  1007. * Arguments::                   Your Program's Arguments
  1008. * Environment::                 Your Program's Environment
  1009. * Working Directory::           Your Program's Working Directory
  1010. * Input/Output::                Your Program's Input and Output
  1011. * Attach::                      Debugging an Already-Running Process
  1012. * Kill Process::                Killing the Child Process
  1013. * Process Information::         Additional Process Information
  1014.  
  1015. 
  1016. File: gdb.info,  Node: Compilation,  Next: Starting,  Up: Running
  1017.  
  1018. Compiling for Debugging
  1019. =======================
  1020.  
  1021.    In order to debug a program effectively, you need to generate
  1022. debugging information when you compile it.  This debugging information
  1023. is stored in the object file; it describes the data type of each
  1024. variable or function and the correspondence between source line numbers
  1025. and addresses in the executable code.
  1026.  
  1027.    To request debugging information, specify the `-g' option when you
  1028. run the compiler.
  1029.  
  1030.    Many C compilers are unable to handle the `-g' and `-O' options
  1031. together.  Using those compilers, you cannot generate optimized
  1032. executables containing debugging information.
  1033.  
  1034.    gcc, the GNU C compiler, supports `-g' with or without `-O', making
  1035. it possible to debug optimized code.  We recommend that you *always*
  1036. use `-g' whenever you compile a program. You may think your program is
  1037. correct, but there is no sense in pushing your luck.
  1038.  
  1039.    When you debug a program compiled with `-g -O', remember that the
  1040. optimizer is rearranging your code; the debugger will show you what's
  1041. really there.  Don't be too surprised when the execution path doesn't
  1042. exactly match your source file!  An extreme example: if you define a
  1043. variable, but never use it, GDB will never see that variable--because
  1044. the compiler optimizes it out of existence.
  1045.  
  1046.    Some things do not work as well with `-g -O' as with just `-g',
  1047. particularly on machines with instruction scheduling.  If in doubt,
  1048. recompile with `-g' alone, and if this fixes the problem, please report
  1049. it as a bug (including a test case!).
  1050.  
  1051.    Older versions of the GNU C compiler permitted a variant option
  1052. `-gg' for debugging information.  GDB no longer supports this format;
  1053. if your GNU C compiler has this option, do not use it.
  1054.  
  1055. 
  1056. File: gdb.info,  Node: Starting,  Next: Arguments,  Prev: Compilation,  Up: Running
  1057.  
  1058. Starting your Program
  1059. =====================
  1060.  
  1061. `run'
  1062. `r'
  1063.      Use the `run' command to start your program under GDB.  You must
  1064.      first specify the program name (except on VxWorks) with an
  1065.      argument to GDB (*note Getting In and Out of GDB: Invocation.), or
  1066.      by using the `file' or `exec-file' command (*note Commands to
  1067.      Specify Files: Files.).
  1068.  
  1069.    If you are running your program in an execution environment that
  1070. supports processes, `run' creates an inferior process and makes that
  1071. process run your program.  (In environments without processes, `run'
  1072. jumps to the start of your program.)
  1073.  
  1074.    The execution of a program is affected by certain information it
  1075. receives from its superior.  GDB provides ways to specify this
  1076. information, which you must do *before* starting your program.  (You
  1077. can change it after starting your program, but such changes will only
  1078. affect your program the next time you start it.)  This information may
  1079. be divided into four categories:
  1080.  
  1081. The *arguments.*
  1082.      Specify the arguments to give your program as the arguments of the
  1083.      `run' command.  If a shell is available on your target, the shell
  1084.      is used to pass the arguments, so that you may use normal
  1085.      conventions (such as wildcard expansion or variable substitution)
  1086.      in describing the arguments.  In Unix systems, you can control
  1087.      which shell is used with the `SHELL' environment variable. *Note
  1088.      Your Program's Arguments: Arguments.
  1089.  
  1090. The *environment.*
  1091.      Your program normally inherits its environment from GDB, but you
  1092.      can use the GDB commands `set environment' and `unset environment'
  1093.      to change parts of the environment that will be given to your
  1094.      program.  *Note Your Program's Environment: Environment.
  1095.  
  1096. The *working directory.*
  1097.      Your program inherits its working directory from GDB.  You can set
  1098.      GDB's working directory with the `cd' command in GDB. *Note Your
  1099.      Program's Working Directory: Working Directory.
  1100.  
  1101. The *standard input and output.*
  1102.      Your program normally uses the same device for standard input and
  1103.      standard output as GDB is using.  You can redirect input and output
  1104.      in the `run' command line, or you can use the `tty' command to set
  1105.      a different device for your program. *Note Your Program's Input
  1106.      and Output: Input/Output.
  1107.  
  1108.      *Warning:* While input and output redirection work, you cannot use
  1109.      pipes to pass the output of the program you are debugging to
  1110.      another program; if you attempt this, GDB is likely to wind up
  1111.      debugging the wrong program.
  1112.  
  1113.    When you issue the `run' command, your program begins to execute
  1114. immediately.  *Note Stopping and Continuing: Stopping, for discussion
  1115. of how to arrange for your program to stop.  Once your program has
  1116. stopped, you may calls functions in your program, using the `print' or
  1117. `call' commands.  *Note Examining Data: Data.
  1118.  
  1119.    If the modification time of your symbol file has changed since the
  1120. last time GDB read its symbols, GDB will discard its symbol table and
  1121. re-read it.  When it does this, GDB tries to retain your current
  1122. breakpoints.
  1123.  
  1124. 
  1125. File: gdb.info,  Node: Arguments,  Next: Environment,  Prev: Starting,  Up: Running
  1126.  
  1127. Your Program's Arguments
  1128. ========================
  1129.  
  1130.    The arguments to your program can be specified by the arguments of
  1131. the `run' command.  They are passed to a shell, which expands wildcard
  1132. characters and performs redirection of I/O, and thence to your program.
  1133. GDB uses the shell indicated by your environment variable `SHELL' if it
  1134. exists; otherwise, GDB uses `/bin/sh'.
  1135.  
  1136.    `run' with no arguments uses the same arguments used by the previous
  1137. `run', or those set by the `set args' command.
  1138.  
  1139. `set args'
  1140.      Specify the arguments to be used the next time your program is
  1141.      run.  If `set args' has no arguments, `run' will execute your
  1142.      program with no arguments.  Once you have run your program with
  1143.      arguments, using `set args' before the next `run' is the only way
  1144.      to run it again without arguments.
  1145.  
  1146. `show args'
  1147.      Show the arguments to give your program when it is started.
  1148.  
  1149. 
  1150. File: gdb.info,  Node: Environment,  Next: Working Directory,  Prev: Arguments,  Up: Running
  1151.  
  1152. Your Program's Environment
  1153. ==========================
  1154.  
  1155.    The "environment" consists of a set of environment variables and
  1156. their values.  Environment variables conventionally record such things
  1157. as your user name, your home directory, your terminal type, and your
  1158. search path for programs to run.  Usually you set up environment
  1159. variables with the shell and they are inherited by all the other
  1160. programs you run.  When debugging, it can be useful to try running your
  1161. program with a modified environment without having to start GDB over
  1162. again.
  1163.  
  1164. `path DIRECTORY'
  1165.      Add DIRECTORY to the front of the `PATH' environment variable (the
  1166.      search path for executables), for both GDB and your program. You
  1167.      may specify several directory names, separated by `:' or
  1168.      whitespace.  If DIRECTORY is already in the path, it is moved to
  1169.      the front, so it will be searched sooner.
  1170.  
  1171.      You can use the string `$cwd' to refer to whatever is the current
  1172.      working directory at the time GDB searches the path.  If you use
  1173.      `.' instead, it refers to the directory where you executed the
  1174.      `path' command.  GDB fills in the current path where needed in the
  1175.      DIRECTORY argument, before adding it to the search path.
  1176.  
  1177. `show paths'
  1178.      Display the list of search paths for executables (the `PATH'
  1179.      environment variable).
  1180.  
  1181. `show environment [VARNAME]'
  1182.      Print the value of environment variable VARNAME to be given to
  1183.      your program when it starts.  If you do not supply VARNAME, print
  1184.      the names and values of all environment variables to be given to
  1185.      your program.  You can abbreviate `environment' as `env'.
  1186.  
  1187. `set environment VARNAME [=] VALUE'
  1188.      Sets environment variable VARNAME to VALUE.  The value changes for
  1189.      your program only, not for GDB itself.  VALUE may be any string;
  1190.      the values of environment variables are just strings, and any
  1191.      interpretation is supplied by your program itself.  The VALUE
  1192.      parameter is optional; if it is eliminated, the variable is set to
  1193.      a null value.
  1194.  
  1195.      For example, this command:
  1196.  
  1197.           set env USER = foo
  1198.  
  1199.      tells a Unix program, when subsequently run, that its user is named
  1200.      `foo'.  (The spaces around `=' are used for clarity here; they are
  1201.      not actually required.)
  1202.  
  1203. `unset environment VARNAME'
  1204.      Remove variable VARNAME from the environment to be passed to your
  1205.      program.  This is different from `set env VARNAME ='; `unset
  1206.      environment' removes the variable from the environment, rather
  1207.      than assigning it an empty value.
  1208.  
  1209. 
  1210. File: gdb.info,  Node: Working Directory,  Next: Input/Output,  Prev: Environment,  Up: Running
  1211.  
  1212. Your Program's Working Directory
  1213. ================================
  1214.  
  1215.    Each time you start your program with `run', it inherits its working
  1216. directory from the current working directory of GDB.  GDB's working
  1217. directory is initially whatever it inherited from its parent process
  1218. (typically the shell), but you can specify a new working directory in
  1219. GDB with the `cd' command.
  1220.  
  1221.    The GDB working directory also serves as a default for the commands
  1222. that specify files for GDB to operate on.  *Note Commands to Specify
  1223. Files: Files.
  1224.  
  1225. `cd DIRECTORY'
  1226.      Set GDB's working directory to DIRECTORY.
  1227.  
  1228. `pwd'
  1229.      Print GDB's working directory.
  1230.  
  1231. 
  1232. File: gdb.info,  Node: Input/Output,  Next: Attach,  Prev: Working Directory,  Up: Running
  1233.  
  1234. Your Program's Input and Output
  1235. ===============================
  1236.  
  1237.    By default, the program you run under GDB does input and output to
  1238. the same terminal that GDB uses.  GDB switches the terminal to its own
  1239. terminal modes to interact with you, but it records the terminal modes
  1240. your program was using and switches back to them when you continue
  1241. running your program.
  1242.  
  1243. `info terminal'
  1244.      Displays GDB's recorded information about the terminal modes your
  1245.      program is using.
  1246.  
  1247.    You can redirect your program's input and/or output using shell
  1248. redirection with the `run' command.  For example,
  1249.  
  1250.      run > outfile
  1251.  
  1252. starts your program, diverting its output to the file `outfile'.
  1253.  
  1254.    Another way to specify where your program should do input and output
  1255. is with the `tty' command.  This command accepts a file name as
  1256. argument, and causes this file to be the default for future `run'
  1257. commands.  It also resets the controlling terminal for the child
  1258. process, for future `run' commands.  For example,
  1259.  
  1260.      tty /dev/ttyb
  1261.  
  1262. directs that processes started with subsequent `run' commands default
  1263. to do input and output on the terminal `/dev/ttyb' and have that as
  1264. their controlling terminal.
  1265.  
  1266.    An explicit redirection in `run' overrides the `tty' command's
  1267. effect on the input/output device, but not its effect on the controlling
  1268. terminal.
  1269.  
  1270.    When you use the `tty' command or redirect input in the `run'
  1271. command, only the input *for your program* is affected.  The input for
  1272. GDB still comes from your terminal.
  1273.  
  1274.