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.
5 @node Invocation, Commands, Sample Session, Top
6 @chapter Getting In and Out of _GDBN__
9 * Starting _GDBN__:: Starting _GDBN__
10 * Leaving _GDBN__:: Leaving _GDBN__
11 * Shell Commands:: Shell Commands
14 @node Starting _GDBN__, Leaving _GDBN__, Invocation, Invocation
15 @section Starting _GDBN__
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.
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:
27 You can also start with both an executable program and a core file specified:
33 You can further control how _GDBN__ starts up by using command-line
34 options. _GDBN__ itself can remind you of the options available:
39 will display all available options and briefly describe their use
40 (@samp{_GDBP__ -h} is a shorter equivalent).
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.
47 * File Options:: Choosing Files
48 * Mode Options:: Choosing Modes
50 _include__(gdb.inv.m-m4)_dnl__
54 @node File Options, Mode Options, Starting _GDBN__, Starting _GDBN__
55 @subsection Choosing Files
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.)
68 @item -symbols=@var{file}
70 Read symbol table from file @var{file}.
72 @item -exec=@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
79 Read symbol table from file @var{file} and use it as the executable
82 @item -core=@var{file}
84 Use file @var{file} as a core dump to examine.
86 @item -command=@var{file}
88 Execute _GDBN__ commands from file @var{file}. @xref{Command Files}.
90 @item -directory=@var{directory}
91 @itemx -d @var{directory}
92 Add @var{directory} to the path to search for source files.
96 @node Mode Options, i960-Nindy Remote, File Options, Starting _GDBN__
99 @node Mode Options, , File Options, Starting _GDBN__
101 @subsection Choosing Modes
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
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.
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.
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
127 Program exited normally.
130 (which is ordinarily issued whenever a program running under _GDBN__ control
131 terminates) is not issued when running in batch mode.
133 @item -cd @var{directory}
134 Run _GDBN__ using @var{directory} as its working directory,
135 instead of the current directory.
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.
149 Set the line speed (baud rate or bits per second) of any serial
150 interface used by _GDBN__ for remote debugging.
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.
158 _include__(gdb.inv.s-m4)
161 @node Leaving _GDBN__, Shell Commands, Starting _GDBN__, Invocation
162 @section Leaving _GDBN__
163 @cindex exiting _GDBN__
168 To exit _GDBN__, use the @code{quit} command (abbreviated @code{q}), or type
169 an end-of-file character (usually @kbd{C-d}).
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.
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}.
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.
189 @item shell @var{command string}
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
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__:
202 @item make @var{make-args}
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}}.