diff options
Diffstat (limited to 'gdb/doc/gdb.run-m4')
| -rwxr-xr-x | gdb/doc/gdb.run-m4 | 390 |
1 files changed, 0 insertions, 390 deletions
diff --git a/gdb/doc/gdb.run-m4 b/gdb/doc/gdb.run-m4 index 09df60b..e69de29 100755 --- a/gdb/doc/gdb.run-m4 +++ b/gdb/doc/gdb.run-m4 @@ -1,390 +0,0 @@ -_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). |