Commit | Line | Data |
---|---|---|
9bcc06ef RP |
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. | |
ff2e4391 | 4 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
5 | @node Invocation, Commands, Sample Session, Top |
6 | @chapter Getting In and Out of _GDBN__ | |
7 | ||
8 | @menu | |
9 | * Starting _GDBN__:: Starting _GDBN__ | |
ff2e4391 | 10 | * Leaving _GDBN__:: Leaving _GDBN__ |
9bcc06ef RP |
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 | ||
ff2e4391 | 95 | _if__(!_GENERIC__) |
9bcc06ef | 96 | @node Mode Options, i960-Nindy Remote, File Options, Starting _GDBN__ |
ff2e4391 RP |
97 | _fi__(!_GENERIC__) |
98 | _if__(_GENERIC__) | |
99 | @node Mode Options, , File Options, Starting _GDBN__ | |
100 | _fi__(_GENERIC__) | |
9bcc06ef RP |
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 |