390 lines
15 KiB
Text
Executable file
390 lines
15 KiB
Text
Executable file
_dnl__ -*- Texinfo -*-
|
|
_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
|
|
_dnl__ This file is part of the source for the GDB manual.
|
|
_dnl__ $Id$
|
|
@node Running, Stopping, Commands, Top
|
|
@chapter Running Programs Under _GDBN__
|
|
|
|
@menu
|
|
* Compilation:: Compiling for Debugging
|
|
* Starting:: Starting your Program
|
|
* Arguments:: Your Program's Arguments
|
|
* Environment:: Your Program's Environment
|
|
* Working Directory:: Your Program's Working Directory
|
|
* Input/Output:: Your Program's Input and Output
|
|
* Attach:: Debugging an Already-Running Process
|
|
* Kill Process:: Killing the Child Process
|
|
@end menu
|
|
|
|
@node Compilation, Starting, Running, Running
|
|
@section Compiling for Debugging
|
|
|
|
In order to debug a program effectively, you need to generate
|
|
debugging information when you compile it. This debugging information
|
|
is stored in the object file; it describes the data type of each
|
|
variable or function and the correspondence between source line numbers
|
|
and addresses in the executable code.
|
|
|
|
To request debugging information, specify the @samp{-g} option when you run
|
|
the compiler.
|
|
|
|
Many C compilers are unable to handle the @samp{-g} and @samp{-O}
|
|
options together. Using those compilers, you cannot generate optimized
|
|
executables containing debugging information.
|
|
|
|
The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
|
|
possible to debug optimized code. We recommend that you @emph{always} use
|
|
@samp{-g} whenever you compile a program. You may think the program is
|
|
correct, but there's no sense in pushing your luck.
|
|
|
|
Some things do not work as well with @samp{-g -O} as with just
|
|
@samp{-g}, particularly on machines with instruction scheduling. If in
|
|
doubt, recompile with @samp{-g} alone, and if this fixes the problem,
|
|
please report it as a bug (including a test case!).
|
|
|
|
Older versions of the GNU C compiler permitted a variant option
|
|
@samp{-gg} for debugging information. _GDBN__ no longer supports this
|
|
format; if your GNU C compiler has this option, do not use it.
|
|
|
|
@ignore
|
|
@comment As far as I know, there are no cases in which _GDBN__ will
|
|
@comment produce strange output in this case. (but no promises).
|
|
If your program includes archives made with the @code{ar} program, and
|
|
if the object files used as input to @code{ar} were compiled without the
|
|
@samp{-g} option and have names longer than 15 characters, _GDBN__ will get
|
|
confused reading the program's symbol table. No error message will be
|
|
given, but _GDBN__ may behave strangely. The reason for this problem is a
|
|
deficiency in the Unix archive file format, which cannot represent file
|
|
names longer than 15 characters.
|
|
|
|
To avoid this problem, compile the archive members with the @samp{-g}
|
|
option or use shorter file names. Alternatively, use a version of GNU
|
|
@code{ar} dated more recently than August 1989.
|
|
@end ignore
|
|
|
|
|
|
@node Starting, Arguments, Compilation, Running
|
|
@section Starting your Program
|
|
@cindex starting
|
|
@cindex running
|
|
@table @code
|
|
@item run
|
|
@itemx r
|
|
@kindex run
|
|
Use the @code{run} command to start your program under _GDBN__.
|
|
_if__(_VXWORKS__)
|
|
Except on VxWorks, you
|
|
_fi__(_VXWORKS__)
|
|
_if__(!_VXWORKS__)
|
|
You
|
|
_fi__(!_VXWORKS__)
|
|
must first specify the program name with an argument to _GDBN__
|
|
(@pxref{Invocation}), or using the @code{file} or @code{exec-file}
|
|
command (@pxref{Files}).@refill
|
|
@end table
|
|
|
|
On targets that support processes, @code{run} creates an inferior
|
|
process and makes that process run your program. On other targets,
|
|
@code{run} jumps to the start of the program.
|
|
|
|
The execution of a program is affected by certain information it
|
|
receives from its superior. _GDBN__ provides ways to specify this
|
|
information, which you must do @i{before} starting the program. (You
|
|
can change it after starting the program, but such changes will only affect
|
|
the program the next time you start it.) This information may be
|
|
divided into four categories:
|
|
|
|
@table @asis
|
|
@item The @i{arguments.}
|
|
You specify the arguments to give your program as the arguments of the
|
|
@code{run} command. If a shell is available on your target, the shell
|
|
is used to pass the arguments, so that you may use normal conventions
|
|
(such as wildcard expansion or variable substitution) in
|
|
describing the arguments. In Unix systems, you can control which shell
|
|
is used with the @code{SHELL} environment variable. @xref{Arguments}.@refill
|
|
|
|
@item The @i{environment.}
|
|
Your program normally inherits its environment from _GDBN__, but you can
|
|
use the _GDBN__ commands @code{set environment} and @code{unset
|
|
environment} to change parts of the environment that will be given to
|
|
the program. @xref{Environment}.@refill
|
|
|
|
@item The @i{working directory.}
|
|
Your program inherits its working directory from _GDBN__. You can set
|
|
_GDBN__'s working directory with the @code{cd} command in _GDBN__.
|
|
@xref{Working Directory}.
|
|
|
|
@item The @i{standard input and output.}
|
|
Your program normally uses the same device for standard input and
|
|
standard output as _GDBN__ is using. You can redirect input and output
|
|
in the @code{run} command line, or you can use the @code{tty} command to
|
|
set a different device for your program.
|
|
@xref{Input/Output}.
|
|
@end table
|
|
|
|
When you issue the @code{run} command, your program begins to execute
|
|
immediately. @xref{Stopping}, for discussion of how to arrange for your
|
|
program to stop. Once your program has been started by the @code{run}
|
|
command (and then stopped), you may evaluate expressions that involve
|
|
calls to functions in the inferior, using the @code{print} or
|
|
@code{call} commands. @xref{Data}.
|
|
|
|
If the modification time of your symbol file has changed since the last
|
|
time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and re-read
|
|
it. In this process, it tries to retain your current breakpoints.
|
|
|
|
@node Arguments, Environment, Starting, Running
|
|
@section Your Program's Arguments
|
|
|
|
@cindex arguments (to your program)
|
|
The arguments to your program can be specified by the arguments of the
|
|
@code{run} command. They are passed to a shell, which expands wildcard
|
|
characters and performs redirection of I/O, and thence to the program.
|
|
_GDBN__ uses the shell indicated by your environment variable
|
|
@code{SHELL} if it exists; otherwise, _GDBN__ uses @code{/bin/sh}.
|
|
|
|
@code{run} with no arguments uses the same arguments used by the previous
|
|
@code{run}, or those set by the @code{set args} command.
|
|
|
|
@kindex set args
|
|
@table @code
|
|
@item set args
|
|
Specify the arguments to be used the next time your program is run. If
|
|
@code{set args} has no arguments, @code{run} will execute your program
|
|
with no arguments. Once you have run your program with arguments, this
|
|
is the only way to run it again without arguments.
|
|
|
|
@item show args
|
|
@kindex show args
|
|
Show the arguments to give your program when it is started.
|
|
@end table
|
|
|
|
@node Environment, Working Directory, Arguments, Running
|
|
@section Your Program's Environment
|
|
|
|
@cindex environment (of your program)
|
|
The @dfn{environment} consists of a set of environment variables and
|
|
their values. Environment variables conventionally record such things as
|
|
your user name, your home directory, your terminal type, and your search
|
|
path for programs to run. Usually you set up environment variables with
|
|
the shell and they are inherited by all the other programs you run. When
|
|
debugging, it can be useful to try running the program with a modified
|
|
environment without having to start _GDBN__ over again.
|
|
|
|
@table @code
|
|
@item path @var{directory}
|
|
@kindex path
|
|
Add @var{directory} to the front of the @code{PATH} environment variable
|
|
(the search path for executables), for both _GDBN__ and your program.
|
|
You may specify several directory names, separated by @samp{:} or
|
|
whitespace. If @var{directory} is already in the path, it is moved to
|
|
the front, so it will be searched sooner. You can use the string
|
|
@samp{$cwd} to refer to whatever is the current working directory at the
|
|
time _GDBN__ searches the path. @footnote{If you use @samp{.} instead,
|
|
it refers to the directory where you executed the @code{path} command.
|
|
_GDBN__ fills in the current path where needed in the @var{directory}
|
|
argument, before adding it to the search path.}
|
|
@c 'path' is explicitly nonrepeatable, but RMS points out it's silly to
|
|
@c document that, since repeating it would be a no-op.
|
|
|
|
@item show paths
|
|
@kindex show paths
|
|
Display the list of search paths for executables (the @code{PATH}
|
|
environment variable).
|
|
|
|
@item show environment @var{varname}
|
|
@kindex show environment
|
|
Print the value of environment variable @var{varname} to be given to
|
|
your program when it starts.
|
|
|
|
@item show environment
|
|
Print the names and values of all environment variables to be given to
|
|
your program.
|
|
|
|
@item set environment @var{varname} @var{value}
|
|
@itemx set environment @var{varname} = @var{value}
|
|
@kindex set environment
|
|
Sets environment variable @var{varname} to @var{value}. The value
|
|
changes for your program only, not for _GDBN__ itself. @var{value} may
|
|
be any string; the values of environment variables are just strings, and
|
|
any interpretation is supplied by your program itself. The @var{value}
|
|
parameter is optional; if it is eliminated, the variable is set to a
|
|
null value.
|
|
@c "any string" here doesn't include leading, trailing
|
|
@c blanks. Gnu asks: does anyone care?
|
|
|
|
For example, this command:
|
|
|
|
@example
|
|
set env USER = foo
|
|
@end example
|
|
|
|
@noindent
|
|
tells a Unix program, when subsequently run, that its user is named
|
|
@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
|
|
are not actually required.)
|
|
|
|
@item unset environment @var{varname}
|
|
@kindex unset environment
|
|
Remove variable @var{varname} from the environment to be passed to your
|
|
program. This is different from @samp{set env @var{varname} =};
|
|
@code{unset environment} removes the variable from the environment,
|
|
rather than assigning it an empty value.
|
|
@end table
|
|
|
|
@node Working Directory, Input/Output, Environment, Running
|
|
@section Your Program's Working Directory
|
|
|
|
@cindex working directory (of your program)
|
|
Each time you start your program with @code{run}, it inherits its
|
|
working directory from the current working directory of _GDBN__. _GDBN__'s
|
|
working directory is initially whatever it inherited from its parent
|
|
process (typically the shell), but you can specify a new working
|
|
directory in _GDBN__ with the @code{cd} command.
|
|
|
|
The _GDBN__ working directory also serves as a default for the commands
|
|
that specify files for _GDBN__ to operate on. @xref{Files}.
|
|
|
|
@table @code
|
|
@item cd @var{directory}
|
|
@kindex cd
|
|
Set _GDBN__'s working directory to @var{directory}.
|
|
|
|
@item pwd
|
|
@kindex pwd
|
|
Print _GDBN__'s working directory.
|
|
@end table
|
|
|
|
@node Input/Output, Attach, Working Directory, Running
|
|
@section Your Program's Input and Output
|
|
|
|
@cindex redirection
|
|
@cindex i/o
|
|
@cindex terminal
|
|
@cindex controlling terminal
|
|
By default, the program you run under _GDBN__ does input and output to
|
|
the same terminal that _GDBN__ uses. _GDBN__ switches the terminal to
|
|
its own terminal modes to interact with you, but it records the terminal
|
|
modes your program was using and switches back to them when you continue
|
|
running your program.
|
|
|
|
@table @code
|
|
@item info terminal
|
|
@kindex info terminal
|
|
Displays _GDBN__'s recorded information about the terminal modes your
|
|
program is using.
|
|
@end table
|
|
|
|
You can redirect the program's input and/or output using shell
|
|
redirection with the @code{run} command. For example,
|
|
|
|
_0__@example
|
|
run > outfile
|
|
_1__@end example
|
|
|
|
@noindent
|
|
starts the program, diverting its output to the file @file{outfile}.
|
|
|
|
@kindex tty
|
|
Another way to specify where the program should do input and output is
|
|
with the @code{tty} command. This command accepts a file name as
|
|
argument, and causes this file to be the default for future @code{run}
|
|
commands. It also resets the controlling terminal for the child
|
|
process, for future @code{run} commands. For example,
|
|
|
|
@example
|
|
tty /dev/ttyb
|
|
@end example
|
|
|
|
@noindent
|
|
directs that processes started with subsequent @code{run} commands
|
|
default to do input and output on the terminal @file{/dev/ttyb} and have
|
|
that as their controlling terminal.
|
|
|
|
An explicit redirection in @code{run} overrides the @code{tty} command's
|
|
effect on the input/output device, but not its effect on the controlling
|
|
terminal.
|
|
|
|
When you use the @code{tty} command or redirect input in the @code{run}
|
|
command, only the input @emph{for your program} is affected. The input
|
|
for _GDBN__ still comes from your terminal.
|
|
|
|
@node Attach, Kill Process, Input/Output, Running
|
|
@section Debugging an Already-Running Process
|
|
@kindex attach
|
|
@cindex attach
|
|
|
|
@table @code
|
|
@item attach @var{process-id}
|
|
This command
|
|
attaches to a running process---one that was started outside _GDBN__.
|
|
(@code{info files} will show your active targets.) The command takes as
|
|
argument a process ID. The usual way to find out the process-id of
|
|
a Unix process is with the @code{ps} utility, or with the @samp{jobs -l}
|
|
shell command.
|
|
|
|
@code{attach} will not repeat if you press @key{RET} a second time after
|
|
executing the command.
|
|
@end table
|
|
|
|
To use @code{attach}, you must be debugging in an environment which
|
|
supports processes. You must also have permission to send the process a
|
|
signal, and it must have the same effective user ID as the _GDBN__
|
|
process.
|
|
|
|
When using @code{attach}, you should first use the @code{file} command
|
|
to specify the program running in the process and load its symbol table.
|
|
@xref{Files}.
|
|
|
|
The first thing _GDBN__ does after arranging to debug the specified
|
|
process is to stop it. You can examine and modify an attached process
|
|
with all the _GDBN__ commands that ordinarily available when you start
|
|
processes with @code{run}. You can insert breakpoints; you can step and
|
|
continue; you can modify storage. If you would rather the process
|
|
continue running, you may use the @code{continue} command after
|
|
attaching _GDBN__ to the process.
|
|
|
|
@table @code
|
|
@item detach
|
|
@kindex detach
|
|
When you have finished debugging the attached process, you can use the
|
|
@code{detach} command to release it from _GDBN__'s control. Detaching
|
|
the process continues its execution. After the @code{detach} command,
|
|
that process and _GDBN__ become completely independent once more, and you
|
|
are ready to @code{attach} another process or start one with @code{run}.
|
|
@code{detach} will not repeat if you press @key{RET} again after
|
|
executing the command.
|
|
@end table
|
|
|
|
If you exit _GDBN__ or use the @code{run} command while you have an attached
|
|
process, you kill that process. By default, you will be asked for
|
|
confirmation if you try to do either of these things; you can control
|
|
whether or not you need to confirm by using the @code{set confirm} command
|
|
(@pxref{Messages/Warnings}).
|
|
|
|
@group
|
|
@node Kill Process, , Attach, Running
|
|
@section Killing the Child Process
|
|
|
|
@table @code
|
|
@item kill
|
|
@kindex kill
|
|
Kill the child process in which your program is running under _GDBN__.
|
|
@end table
|
|
|
|
This command is useful if you wish to debug a core dump instead of a
|
|
running process. _GDBN__ ignores any core dump file while your program
|
|
is running.
|
|
@end group
|
|
|
|
On some operating systems, you can't execute your program in another
|
|
process while breakpoints are active inside _GDBN__. You can use the
|
|
@code{kill} command in this situation to permit running the program
|
|
outside the debugger.
|
|
|
|
The @code{kill} command is also useful if you wish to recompile and
|
|
relink the program, since on many systems it is impossible to modify an
|
|
executable file which is running in a process. In this case, when you
|
|
next type @code{run}, _GDBN__ will notice that the file has changed, and
|
|
will re-read the symbol table (while trying to preserve your current
|
|
breakpoint settings).
|