From 9bcc06ef1645086025bd7a5ecbe423f7fc1d6fc8 Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Thu, 23 May 1991 00:14:26 +0000 Subject: *** empty log message *** --- gdb/doc/gdb.run-m4 | 390 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100755 gdb/doc/gdb.run-m4 (limited to 'gdb/doc/gdb.run-m4') 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). -- cgit v1.1