path: root/gdb/doc/gdb.invoc-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 Invocation, Commands, Sample Session, Top
@chapter Getting In and Out of _GDBN__

@menu
* Starting _GDBN__::		Starting _GDBN__
* Leaving _GDBN__::			Leaving _GDBN__
* Shell Commands::		Shell Commands
@end menu

@node Starting _GDBN__, Leaving _GDBN__, Invocation, Invocation
@section Starting _GDBN__

_GDBN__ is invoked with the shell command @code{_GDBP__}.  Once started,
it reads commands from the terminal until you tell it to exit.

You can run @code{_GDBP__} with no arguments or options; but the most
usual way to start _GDBN__ is with one argument or two, specifying an
executable program as the argument:
@example
_GDBP__ program
@end example
@noindent
You can also start with both an executable program and a core file specified:
@example
_GDBP__ program core
@end example

@noindent
You can further control how _GDBN__ starts up by using command-line
options.  _GDBN__ itself can remind you of the options available:
@example
_GDBP__ -help
@end example
@noindent
will display all available options and briefly describe their use
(@samp{_GDBP__ -h} is a shorter equivalent).

All options and command line arguments you give are processed
in sequential order.  The order makes a difference when the
@samp{-x} option is used.  

@menu
* File Options::		Choosing Files
* Mode Options::		Choosing Modes
_if__(!_GENERIC__)
_include__(gdb.inv.m-m4)_dnl__
_fi__(!_GENERIC__)
@end menu

@node File Options, Mode Options, Starting _GDBN__, Starting _GDBN__
@subsection Choosing Files

As shown above, any arguments other than options specify an executable
file and core file; that is, the first argument encountered with no
associated option flag is equivalent to a @samp{-se} option, and the
second, if any, is equivalent to a @samp{-c} option.  Many options have
both long and short forms; both are shown here.  The long forms are also
recognized if you truncate them, so long as enough of the option is
present to be unambiguous.  (If you prefer, you can flag option
arguments with @samp{+} rather than @samp{-}, though we illustrate the
more usual convention.)

@table @code
@item -symbols=@var{file}
@itemx -s @var{file}
Read symbol table from file @var{file}.

@item -exec=@var{file}
@itemx -e @var{file}
Use file @var{file} as the executable file to execute when
appropriate, and for examining pure data in conjunction with a core
dump.

@item -se @var{file}
Read symbol table from file @var{file} and use it as the executable
file.

@item -core=@var{file}
@itemx -c @var{file}
Use file @var{file} as a core dump to examine.

@item -command=@var{file}
@itemx -x @var{file}
Execute _GDBN__ commands from file @var{file}.  @xref{Command Files}.

@item -directory=@var{directory}
@itemx -d @var{directory}
Add @var{directory} to the path to search for source files.
@end table

_if__(!_GENERIC__)
@node Mode Options, i960-Nindy Remote, File Options, Starting _GDBN__
_fi__(!_GENERIC__)
_if__(_GENERIC__)
@node Mode Options,  , File Options, Starting _GDBN__
_fi__(_GENERIC__)
@subsection Choosing Modes

@table @code
@item -nx
@itemx -n
Do not execute commands from any @file{_GDBINIT__} initialization files.
Normally, the commands in these files are executed after all the
command options and arguments have been processed.  @xref{Command
Files}.

@item -quiet
@itemx -q
``Quiet''.  Do not print the introductory and copyright messages.  These
messages are also suppressed in batch mode, or if an executable file name is
specified on the _GDBN__ command line.

@item -batch
Run in batch mode.  Exit with status @code{0} after processing all the command
files specified with @samp{-x} (and @file{_GDBINIT__}, if not inhibited).
Exit with nonzero status if an error occurs in executing the _GDBN__
commands in the command files.  

Batch mode may be useful for running _GDBN__ as a filter, for example to
download and run a program on another computer; in order to make this
more useful, the message 
@example
Program exited normally.
@end example
@noindent
(which is ordinarily issued whenever a program running under _GDBN__ control
terminates) is not issued when running in batch mode.

@item -cd @var{directory}
Run _GDBN__ using @var{directory} as its working directory,
instead of the current directory.

@item -fullname
@itemx -f
This option is used when Emacs runs _GDBN__ as a subprocess.  It tells _GDBN__
to output the full file name and line number in a standard,
recognizable fashion each time a stack frame is displayed (which
includes each time the program stops).  This recognizable format looks
like two @samp{\032} characters, followed by the file name, line number
and character position separated by colons, and a newline.  The
Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as
a signal to display the source code for the frame.

@item -b @var{bps}
Set the line speed (baud rate or bits per second) of any serial
interface used by _GDBN__ for remote debugging.

@item -tty @var{device}
Run using @var{device} for your program's standard input and output.
@c FIXME: kingdon thinks there's more to -tty.  Investigate.
@end table

_if__(!_GENERIC__)
_include__(gdb.inv.s-m4)
_fi__(!_GENERIC__)

@node Leaving _GDBN__, Shell Commands, Starting _GDBN__, Invocation
@section Leaving _GDBN__
@cindex exiting _GDBN__
@table @code
@item quit
@kindex quit
@kindex q
To exit _GDBN__, use the @code{quit} command (abbreviated @code{q}), or type
an end-of-file character (usually @kbd{C-d}).  
@end table

@cindex interrupt
An interrupt (often @kbd{C-c}) will not exit from _GDBN__, but rather
will terminate the action of any _GDBN__ command that is in progress and
return to _GDBN__ command level.  It is safe to type the interrupt
character at any time because _GDBN__ does not allow it to take effect
until a time when it is safe.

If you've been using _GDBN__ to control an attached process or device,
you can release it with the @code{detach} command; @pxref{Attach}.

@node Shell Commands,  , Leaving _GDBN__, Invocation
@section Shell Commands
If you just need to execute occasional shell commands during your
debugging session, there's no need to leave or suspend _GDBN__; you can
just use the @code{shell} command.

@table @code
@item shell @var{command string}
@kindex shell
@cindex shell escape
Directs _GDBN__ to invoke an inferior shell to execute @var{command
string}.  If it exists, the environment variable @code{SHELL} is used
for the name of the shell to run.  Otherwise _GDBN__ uses
@code{/bin/sh}.
@end table

The utility @code{make} is often needed in development environments.
You don't have to use the @code{shell} command for this purpose in _GDBN__:

@table @code
@item make @var{make-args}
@kindex make
@cindex calling make
Causes _GDBN__ to execute an inferior @code{make} program with the specified
arguments.  This is equivalent to @samp{shell make @var{make-args}}.
@end table