Improve release doc slightly.

[deliverable/binutils-gdb.git] / gdb / doc / gdb.run-m4

_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.
@c M4 FRAGMENT: $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}).

@node Kill Process,  , Attach, Running
@c @group
@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.
@c @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).