gdb/doc/gdb.invoc-m4

   1 _dnl__                                                          -*- Texinfo -*-
   2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
   3 _dnl__ This file is part of the source for the GDB manual.
   4 @c M4 FRAGMENT: $Id$
   5 @node Invocation, Commands, Sample Session, Top
   6 @chapter Getting In and Out of _GDBN__
   7
   8 @menu
   9 * Starting _GDBN__::            Starting _GDBN__
  10 * Leaving _GDBN__::                     Leaving _GDBN__
  11 * Shell Commands::              Shell Commands
  12 @end menu
  13
  14 @node Starting _GDBN__, Leaving _GDBN__, Invocation, Invocation
  15 @section Starting _GDBN__
  16
  17 _GDBN__ is invoked with the shell command @code{_GDBP__}.  Once started,
  18 it reads commands from the terminal until you tell it to exit.
  19
  20 You can run @code{_GDBP__} with no arguments or options; but the most
  21 usual way to start _GDBN__ is with one argument or two, specifying an
  22 executable program as the argument:
  23 @example
  24 _GDBP__ program
  25 @end example
  26 @noindent
  27 You can also start with both an executable program and a core file specified:
  28 @example
  29 _GDBP__ program core
  30 @end example
  31
  32 @noindent
  33 You can further control how _GDBN__ starts up by using command-line
  34 options.  _GDBN__ itself can remind you of the options available:
  35 @example
  36 _GDBP__ -help
  37 @end example
  38 @noindent
  39 will display all available options and briefly describe their use
  40 (@samp{_GDBP__ -h} is a shorter equivalent).
  41
  42 All options and command line arguments you give are processed
  43 in sequential order.  The order makes a difference when the
  44 @samp{-x} option is used.
  45
  46 @menu
  47 * File Options::                Choosing Files
  48 * Mode Options::                Choosing Modes
  49 _if__(!_GENERIC__)
  50 _include__(gdb.inv.m-m4)_dnl__
  51 _fi__(!_GENERIC__)
  52 @end menu
  53
  54 @node File Options, Mode Options, Starting _GDBN__, Starting _GDBN__
  55 @subsection Choosing Files
  56
  57 As shown above, any arguments other than options specify an executable
  58 file and core file; that is, the first argument encountered with no
  59 associated option flag is equivalent to a @samp{-se} option, and the
  60 second, if any, is equivalent to a @samp{-c} option.  Many options have
  61 both long and short forms; both are shown here.  The long forms are also
  62 recognized if you truncate them, so long as enough of the option is
  63 present to be unambiguous.  (If you prefer, you can flag option
  64 arguments with @samp{+} rather than @samp{-}, though we illustrate the
  65 more usual convention.)
  66
  67 @table @code
  68 @item -symbols=@var{file}
  69 @itemx -s @var{file}
  70 Read symbol table from file @var{file}.
  71
  72 @item -exec=@var{file}
  73 @itemx -e @var{file}
  74 Use file @var{file} as the executable file to execute when
  75 appropriate, and for examining pure data in conjunction with a core
  76 dump.
  77
  78 @item -se @var{file}
  79 Read symbol table from file @var{file} and use it as the executable
  80 file.
  81
  82 @item -core=@var{file}
  83 @itemx -c @var{file}
  84 Use file @var{file} as a core dump to examine.
  85
  86 @item -command=@var{file}
  87 @itemx -x @var{file}
  88 Execute _GDBN__ commands from file @var{file}.  @xref{Command Files}.
  89
  90 @item -directory=@var{directory}
  91 @itemx -d @var{directory}
  92 Add @var{directory} to the path to search for source files.
  93 @end table
  94
  95 _if__(!_GENERIC__)
  96 @node Mode Options, i960-Nindy Remote, File Options, Starting _GDBN__
  97 _fi__(!_GENERIC__)
  98 _if__(_GENERIC__)
  99 @node Mode Options,  , File Options, Starting _GDBN__
 100 _fi__(_GENERIC__)
 101 @subsection Choosing Modes
 102
 103 @table @code
 104 @item -nx
 105 @itemx -n
 106 Do not execute commands from any @file{_GDBINIT__} initialization files.
 107 Normally, the commands in these files are executed after all the
 108 command options and arguments have been processed.  @xref{Command
 109 Files}.
 110
 111 @item -quiet
 112 @itemx -q
 113 ``Quiet''.  Do not print the introductory and copyright messages.  These
 114 messages are also suppressed in batch mode, or if an executable file name is
 115 specified on the _GDBN__ command line.
 116
 117 @item -batch
 118 Run in batch mode.  Exit with status @code{0} after processing all the command
 119 files specified with @samp{-x} (and @file{_GDBINIT__}, if not inhibited).
 120 Exit with nonzero status if an error occurs in executing the _GDBN__
 121 commands in the command files.
 122
 123 Batch mode may be useful for running _GDBN__ as a filter, for example to
 124 download and run a program on another computer; in order to make this
 125 more useful, the message
 126 @example
 127 Program exited normally.
 128 @end example
 129 @noindent
 130 (which is ordinarily issued whenever a program running under _GDBN__ control
 131 terminates) is not issued when running in batch mode.
 132
 133 @item -cd @var{directory}
 134 Run _GDBN__ using @var{directory} as its working directory,
 135 instead of the current directory.
 136
 137 @item -fullname
 138 @itemx -f
 139 This option is used when Emacs runs _GDBN__ as a subprocess.  It tells _GDBN__
 140 to output the full file name and line number in a standard,
 141 recognizable fashion each time a stack frame is displayed (which
 142 includes each time the program stops).  This recognizable format looks
 143 like two @samp{\032} characters, followed by the file name, line number
 144 and character position separated by colons, and a newline.  The
 145 Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as
 146 a signal to display the source code for the frame.
 147
 148 @item -b @var{bps}
 149 Set the line speed (baud rate or bits per second) of any serial
 150 interface used by _GDBN__ for remote debugging.
 151
 152 @item -tty @var{device}
 153 Run using @var{device} for your program's standard input and output.
 154 @c FIXME: kingdon thinks there's more to -tty.  Investigate.
 155 @end table
 156
 157 _if__(!_GENERIC__)
 158 _include__(gdb.inv.s-m4)
 159 _fi__(!_GENERIC__)
 160
 161 @node Leaving _GDBN__, Shell Commands, Starting _GDBN__, Invocation
 162 @section Leaving _GDBN__
 163 @cindex exiting _GDBN__
 164 @table @code
 165 @item quit
 166 @kindex quit
 167 @kindex q
 168 To exit _GDBN__, use the @code{quit} command (abbreviated @code{q}), or type
 169 an end-of-file character (usually @kbd{C-d}).
 170 @end table
 171
 172 @cindex interrupt
 173 An interrupt (often @kbd{C-c}) will not exit from _GDBN__, but rather
 174 will terminate the action of any _GDBN__ command that is in progress and
 175 return to _GDBN__ command level.  It is safe to type the interrupt
 176 character at any time because _GDBN__ does not allow it to take effect
 177 until a time when it is safe.
 178
 179 If you've been using _GDBN__ to control an attached process or device,
 180 you can release it with the @code{detach} command; @pxref{Attach}.
 181
 182 @node Shell Commands,  , Leaving _GDBN__, Invocation
 183 @section Shell Commands
 184 If you just need to execute occasional shell commands during your
 185 debugging session, there's no need to leave or suspend _GDBN__; you can
 186 just use the @code{shell} command.
 187
 188 @table @code
 189 @item shell @var{command string}
 190 @kindex shell
 191 @cindex shell escape
 192 Directs _GDBN__ to invoke an inferior shell to execute @var{command
 193 string}.  If it exists, the environment variable @code{SHELL} is used
 194 for the name of the shell to run.  Otherwise _GDBN__ uses
 195 @code{/bin/sh}.
 196 @end table
 197
 198 The utility @code{make} is often needed in development environments.
 199 You don't have to use the @code{shell} command for this purpose in _GDBN__:
 200
 201 @table @code
 202 @item make @var{make-args}
 203 @kindex make
 204 @cindex calling make
 205 Causes _GDBN__ to execute an inferior @code{make} program with the specified
 206 arguments.  This is equivalent to @samp{shell make @var{make-args}}.
 207 @end table