1 files changed, 390 insertions, 0 deletions
diff --git a/gdb/doc/gdb.run-m4 b/gdb/doc/gdb.run-m4
new file mode 100755
index 0000000..cfa42fe
--- /dev/null
+++ b/gdb/doc/gdb.run-m4
@@ -0,0 +1,390 @@
+_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).