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. | |
27189593 | 4 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
5 | @node Running, Stopping, Commands, Top |
6 | @chapter Running Programs Under _GDBN__ | |
7 | ||
8 | @menu | |
9 | * Compilation:: Compiling for Debugging | |
10 | * Starting:: Starting your Program | |
11 | * Arguments:: Your Program's Arguments | |
12 | * Environment:: Your Program's Environment | |
13 | * Working Directory:: Your Program's Working Directory | |
14 | * Input/Output:: Your Program's Input and Output | |
15 | * Attach:: Debugging an Already-Running Process | |
16 | * Kill Process:: Killing the Child Process | |
17 | @end menu | |
18 | ||
19 | @node Compilation, Starting, Running, Running | |
20 | @section Compiling for Debugging | |
21 | ||
22 | In order to debug a program effectively, you need to generate | |
23 | debugging information when you compile it. This debugging information | |
24 | is stored in the object file; it describes the data type of each | |
25 | variable or function and the correspondence between source line numbers | |
26 | and addresses in the executable code. | |
27 | ||
28 | To request debugging information, specify the @samp{-g} option when you run | |
29 | the compiler. | |
30 | ||
31 | Many C compilers are unable to handle the @samp{-g} and @samp{-O} | |
32 | options together. Using those compilers, you cannot generate optimized | |
33 | executables containing debugging information. | |
34 | ||
35 | The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it | |
36 | possible to debug optimized code. We recommend that you @emph{always} use | |
37 | @samp{-g} whenever you compile a program. You may think the program is | |
38 | correct, but there's no sense in pushing your luck. | |
39 | ||
40 | Some things do not work as well with @samp{-g -O} as with just | |
41 | @samp{-g}, particularly on machines with instruction scheduling. If in | |
42 | doubt, recompile with @samp{-g} alone, and if this fixes the problem, | |
43 | please report it as a bug (including a test case!). | |
44 | ||
45 | Older versions of the GNU C compiler permitted a variant option | |
46 | @samp{-gg} for debugging information. _GDBN__ no longer supports this | |
47 | format; if your GNU C compiler has this option, do not use it. | |
48 | ||
49 | @ignore | |
50 | @comment As far as I know, there are no cases in which _GDBN__ will | |
51 | @comment produce strange output in this case. (but no promises). | |
52 | If your program includes archives made with the @code{ar} program, and | |
53 | if the object files used as input to @code{ar} were compiled without the | |
54 | @samp{-g} option and have names longer than 15 characters, _GDBN__ will get | |
55 | confused reading the program's symbol table. No error message will be | |
56 | given, but _GDBN__ may behave strangely. The reason for this problem is a | |
57 | deficiency in the Unix archive file format, which cannot represent file | |
58 | names longer than 15 characters. | |
59 | ||
60 | To avoid this problem, compile the archive members with the @samp{-g} | |
61 | option or use shorter file names. Alternatively, use a version of GNU | |
62 | @code{ar} dated more recently than August 1989. | |
63 | @end ignore | |
64 | ||
65 | ||
66 | @node Starting, Arguments, Compilation, Running | |
67 | @section Starting your Program | |
68 | @cindex starting | |
69 | @cindex running | |
70 | @table @code | |
71 | @item run | |
72 | @itemx r | |
73 | @kindex run | |
74 | Use the @code{run} command to start your program under _GDBN__. | |
75 | _if__(_VXWORKS__) | |
76 | Except on VxWorks, you | |
77 | _fi__(_VXWORKS__) | |
78 | _if__(!_VXWORKS__) | |
79 | You | |
80 | _fi__(!_VXWORKS__) | |
81 | must first specify the program name with an argument to _GDBN__ | |
82 | (@pxref{Invocation}), or using the @code{file} or @code{exec-file} | |
83 | command (@pxref{Files}).@refill | |
84 | @end table | |
85 | ||
86 | On targets that support processes, @code{run} creates an inferior | |
87 | process and makes that process run your program. On other targets, | |
88 | @code{run} jumps to the start of the program. | |
89 | ||
90 | The execution of a program is affected by certain information it | |
91 | receives from its superior. _GDBN__ provides ways to specify this | |
92 | information, which you must do @i{before} starting the program. (You | |
93 | can change it after starting the program, but such changes will only affect | |
94 | the program the next time you start it.) This information may be | |
95 | divided into four categories: | |
96 | ||
97 | @table @asis | |
98 | @item The @i{arguments.} | |
99 | You specify the arguments to give your program as the arguments of the | |
100 | @code{run} command. If a shell is available on your target, the shell | |
101 | is used to pass the arguments, so that you may use normal conventions | |
102 | (such as wildcard expansion or variable substitution) in | |
103 | describing the arguments. In Unix systems, you can control which shell | |
104 | is used with the @code{SHELL} environment variable. @xref{Arguments}.@refill | |
105 | ||
106 | @item The @i{environment.} | |
107 | Your program normally inherits its environment from _GDBN__, but you can | |
108 | use the _GDBN__ commands @code{set environment} and @code{unset | |
109 | environment} to change parts of the environment that will be given to | |
110 | the program. @xref{Environment}.@refill | |
111 | ||
112 | @item The @i{working directory.} | |
113 | Your program inherits its working directory from _GDBN__. You can set | |
114 | _GDBN__'s working directory with the @code{cd} command in _GDBN__. | |
115 | @xref{Working Directory}. | |
116 | ||
117 | @item The @i{standard input and output.} | |
118 | Your program normally uses the same device for standard input and | |
119 | standard output as _GDBN__ is using. You can redirect input and output | |
120 | in the @code{run} command line, or you can use the @code{tty} command to | |
121 | set a different device for your program. | |
122 | @xref{Input/Output}. | |
123 | @end table | |
124 | ||
125 | When you issue the @code{run} command, your program begins to execute | |
126 | immediately. @xref{Stopping}, for discussion of how to arrange for your | |
127 | program to stop. Once your program has been started by the @code{run} | |
128 | command (and then stopped), you may evaluate expressions that involve | |
129 | calls to functions in the inferior, using the @code{print} or | |
130 | @code{call} commands. @xref{Data}. | |
131 | ||
132 | If the modification time of your symbol file has changed since the last | |
133 | time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and re-read | |
134 | it. In this process, it tries to retain your current breakpoints. | |
135 | ||
136 | @node Arguments, Environment, Starting, Running | |
137 | @section Your Program's Arguments | |
138 | ||
139 | @cindex arguments (to your program) | |
140 | The arguments to your program can be specified by the arguments of the | |
141 | @code{run} command. They are passed to a shell, which expands wildcard | |
142 | characters and performs redirection of I/O, and thence to the program. | |
143 | _GDBN__ uses the shell indicated by your environment variable | |
144 | @code{SHELL} if it exists; otherwise, _GDBN__ uses @code{/bin/sh}. | |
145 | ||
146 | @code{run} with no arguments uses the same arguments used by the previous | |
147 | @code{run}, or those set by the @code{set args} command. | |
148 | ||
149 | @kindex set args | |
150 | @table @code | |
151 | @item set args | |
152 | Specify the arguments to be used the next time your program is run. If | |
153 | @code{set args} has no arguments, @code{run} will execute your program | |
154 | with no arguments. Once you have run your program with arguments, this | |
155 | is the only way to run it again without arguments. | |
156 | ||
157 | @item show args | |
158 | @kindex show args | |
159 | Show the arguments to give your program when it is started. | |
160 | @end table | |
161 | ||
162 | @node Environment, Working Directory, Arguments, Running | |
163 | @section Your Program's Environment | |
164 | ||
165 | @cindex environment (of your program) | |
166 | The @dfn{environment} consists of a set of environment variables and | |
167 | their values. Environment variables conventionally record such things as | |
168 | your user name, your home directory, your terminal type, and your search | |
169 | path for programs to run. Usually you set up environment variables with | |
170 | the shell and they are inherited by all the other programs you run. When | |
171 | debugging, it can be useful to try running the program with a modified | |
172 | environment without having to start _GDBN__ over again. | |
173 | ||
174 | @table @code | |
175 | @item path @var{directory} | |
176 | @kindex path | |
177 | Add @var{directory} to the front of the @code{PATH} environment variable | |
178 | (the search path for executables), for both _GDBN__ and your program. | |
179 | You may specify several directory names, separated by @samp{:} or | |
180 | whitespace. If @var{directory} is already in the path, it is moved to | |
181 | the front, so it will be searched sooner. You can use the string | |
182 | @samp{$cwd} to refer to whatever is the current working directory at the | |
183 | time _GDBN__ searches the path. @footnote{If you use @samp{.} instead, | |
184 | it refers to the directory where you executed the @code{path} command. | |
185 | _GDBN__ fills in the current path where needed in the @var{directory} | |
186 | argument, before adding it to the search path.} | |
187 | @c 'path' is explicitly nonrepeatable, but RMS points out it's silly to | |
188 | @c document that, since repeating it would be a no-op. | |
189 | ||
190 | @item show paths | |
191 | @kindex show paths | |
192 | Display the list of search paths for executables (the @code{PATH} | |
193 | environment variable). | |
194 | ||
195 | @item show environment @var{varname} | |
196 | @kindex show environment | |
197 | Print the value of environment variable @var{varname} to be given to | |
198 | your program when it starts. | |
199 | ||
200 | @item show environment | |
201 | Print the names and values of all environment variables to be given to | |
202 | your program. | |
203 | ||
204 | @item set environment @var{varname} @var{value} | |
205 | @itemx set environment @var{varname} = @var{value} | |
206 | @kindex set environment | |
207 | Sets environment variable @var{varname} to @var{value}. The value | |
208 | changes for your program only, not for _GDBN__ itself. @var{value} may | |
209 | be any string; the values of environment variables are just strings, and | |
210 | any interpretation is supplied by your program itself. The @var{value} | |
211 | parameter is optional; if it is eliminated, the variable is set to a | |
212 | null value. | |
213 | @c "any string" here doesn't include leading, trailing | |
214 | @c blanks. Gnu asks: does anyone care? | |
215 | ||
216 | For example, this command: | |
217 | ||
218 | @example | |
219 | set env USER = foo | |
220 | @end example | |
221 | ||
222 | @noindent | |
223 | tells a Unix program, when subsequently run, that its user is named | |
224 | @samp{foo}. (The spaces around @samp{=} are used for clarity here; they | |
225 | are not actually required.) | |
226 | ||
227 | @item unset environment @var{varname} | |
228 | @kindex unset environment | |
229 | Remove variable @var{varname} from the environment to be passed to your | |
230 | program. This is different from @samp{set env @var{varname} =}; | |
231 | @code{unset environment} removes the variable from the environment, | |
232 | rather than assigning it an empty value. | |
233 | @end table | |
234 | ||
235 | @node Working Directory, Input/Output, Environment, Running | |
236 | @section Your Program's Working Directory | |
237 | ||
238 | @cindex working directory (of your program) | |
239 | Each time you start your program with @code{run}, it inherits its | |
240 | working directory from the current working directory of _GDBN__. _GDBN__'s | |
241 | working directory is initially whatever it inherited from its parent | |
242 | process (typically the shell), but you can specify a new working | |
243 | directory in _GDBN__ with the @code{cd} command. | |
244 | ||
245 | The _GDBN__ working directory also serves as a default for the commands | |
246 | that specify files for _GDBN__ to operate on. @xref{Files}. | |
247 | ||
248 | @table @code | |
249 | @item cd @var{directory} | |
250 | @kindex cd | |
251 | Set _GDBN__'s working directory to @var{directory}. | |
252 | ||
253 | @item pwd | |
254 | @kindex pwd | |
255 | Print _GDBN__'s working directory. | |
256 | @end table | |
257 | ||
258 | @node Input/Output, Attach, Working Directory, Running | |
259 | @section Your Program's Input and Output | |
260 | ||
261 | @cindex redirection | |
262 | @cindex i/o | |
263 | @cindex terminal | |
264 | @cindex controlling terminal | |
265 | By default, the program you run under _GDBN__ does input and output to | |
266 | the same terminal that _GDBN__ uses. _GDBN__ switches the terminal to | |
267 | its own terminal modes to interact with you, but it records the terminal | |
268 | modes your program was using and switches back to them when you continue | |
269 | running your program. | |
270 | ||
271 | @table @code | |
272 | @item info terminal | |
273 | @kindex info terminal | |
274 | Displays _GDBN__'s recorded information about the terminal modes your | |
275 | program is using. | |
276 | @end table | |
277 | ||
278 | You can redirect the program's input and/or output using shell | |
279 | redirection with the @code{run} command. For example, | |
280 | ||
281 | _0__@example | |
282 | run > outfile | |
283 | _1__@end example | |
284 | ||
285 | @noindent | |
286 | starts the program, diverting its output to the file @file{outfile}. | |
287 | ||
288 | @kindex tty | |
289 | Another way to specify where the program should do input and output is | |
290 | with the @code{tty} command. This command accepts a file name as | |
291 | argument, and causes this file to be the default for future @code{run} | |
292 | commands. It also resets the controlling terminal for the child | |
293 | process, for future @code{run} commands. For example, | |
294 | ||
295 | @example | |
296 | tty /dev/ttyb | |
297 | @end example | |
298 | ||
299 | @noindent | |
300 | directs that processes started with subsequent @code{run} commands | |
301 | default to do input and output on the terminal @file{/dev/ttyb} and have | |
302 | that as their controlling terminal. | |
303 | ||
304 | An explicit redirection in @code{run} overrides the @code{tty} command's | |
305 | effect on the input/output device, but not its effect on the controlling | |
306 | terminal. | |
307 | ||
308 | When you use the @code{tty} command or redirect input in the @code{run} | |
309 | command, only the input @emph{for your program} is affected. The input | |
310 | for _GDBN__ still comes from your terminal. | |
311 | ||
312 | @node Attach, Kill Process, Input/Output, Running | |
313 | @section Debugging an Already-Running Process | |
314 | @kindex attach | |
315 | @cindex attach | |
316 | ||
317 | @table @code | |
318 | @item attach @var{process-id} | |
319 | This command | |
320 | attaches to a running process---one that was started outside _GDBN__. | |
321 | (@code{info files} will show your active targets.) The command takes as | |
322 | argument a process ID. The usual way to find out the process-id of | |
323 | a Unix process is with the @code{ps} utility, or with the @samp{jobs -l} | |
324 | shell command. | |
325 | ||
326 | @code{attach} will not repeat if you press @key{RET} a second time after | |
327 | executing the command. | |
328 | @end table | |
329 | ||
330 | To use @code{attach}, you must be debugging in an environment which | |
331 | supports processes. You must also have permission to send the process a | |
332 | signal, and it must have the same effective user ID as the _GDBN__ | |
333 | process. | |
334 | ||
335 | When using @code{attach}, you should first use the @code{file} command | |
336 | to specify the program running in the process and load its symbol table. | |
337 | @xref{Files}. | |
338 | ||
339 | The first thing _GDBN__ does after arranging to debug the specified | |
340 | process is to stop it. You can examine and modify an attached process | |
341 | with all the _GDBN__ commands that ordinarily available when you start | |
342 | processes with @code{run}. You can insert breakpoints; you can step and | |
343 | continue; you can modify storage. If you would rather the process | |
344 | continue running, you may use the @code{continue} command after | |
345 | attaching _GDBN__ to the process. | |
346 | ||
347 | @table @code | |
348 | @item detach | |
349 | @kindex detach | |
350 | When you have finished debugging the attached process, you can use the | |
351 | @code{detach} command to release it from _GDBN__'s control. Detaching | |
352 | the process continues its execution. After the @code{detach} command, | |
353 | that process and _GDBN__ become completely independent once more, and you | |
354 | are ready to @code{attach} another process or start one with @code{run}. | |
355 | @code{detach} will not repeat if you press @key{RET} again after | |
356 | executing the command. | |
357 | @end table | |
358 | ||
359 | If you exit _GDBN__ or use the @code{run} command while you have an attached | |
360 | process, you kill that process. By default, you will be asked for | |
361 | confirmation if you try to do either of these things; you can control | |
362 | whether or not you need to confirm by using the @code{set confirm} command | |
363 | (@pxref{Messages/Warnings}). | |
364 | ||
9bcc06ef | 365 | @node Kill Process, , Attach, Running |
27189593 | 366 | @c @group |
9bcc06ef RP |
367 | @section Killing the Child Process |
368 | ||
369 | @table @code | |
370 | @item kill | |
371 | @kindex kill | |
372 | Kill the child process in which your program is running under _GDBN__. | |
373 | @end table | |
374 | ||
375 | This command is useful if you wish to debug a core dump instead of a | |
376 | running process. _GDBN__ ignores any core dump file while your program | |
377 | is running. | |
27189593 | 378 | @c @end group |
9bcc06ef RP |
379 | |
380 | On some operating systems, you can't execute your program in another | |
381 | process while breakpoints are active inside _GDBN__. You can use the | |
382 | @code{kill} command in this situation to permit running the program | |
383 | outside the debugger. | |
384 | ||
385 | The @code{kill} command is also useful if you wish to recompile and | |
386 | relink the program, since on many systems it is impossible to modify an | |
387 | executable file which is running in a process. In this case, when you | |
388 | next type @code{run}, _GDBN__ will notice that the file has changed, and | |
389 | will re-read the symbol table (while trying to preserve your current | |
390 | breakpoint settings). |