From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22555 invoked by alias); 4 Apr 2013 17:15:04 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 22533 invoked by uid 89); 4 Apr 2013 17:15:04 -0000 X-Spam-SWARE-Status: No, score=-7.5 required=5.0 tests=AWL,BAYES_00,KHOP_RCVD_UNTRUST,RCVD_IN_DNSWL_HI,RCVD_IN_HOSTKARMA_W,RP_MATCHES_RCVD,SPF_HELO_PASS autolearn=ham version=3.3.1 Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Thu, 04 Apr 2013 17:14:57 +0000 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r34HEt9g007072 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 4 Apr 2013 13:14:55 -0400 Received: from host2.jankratochvil.net (ovpn-116-44.ams2.redhat.com [10.36.116.44]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id r34HEeRJ020499 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NO); Thu, 4 Apr 2013 13:14:44 -0400 Date: Fri, 05 Apr 2013 13:03:00 -0000 From: Jan Kratochvil To: Eli Zaretskii Cc: tromey@redhat.com, gdb-patches@sourceware.org Subject: Re: [patchv2+doc] New gdbinit.5 man page + converted gdb.1+gdbserver.1 Message-ID: <20130404171439.GA20464@host2.jankratochvil.net> References: <83621x5x7d.fsf@gnu.org> <20130212162141.GA4287@host2.jankratochvil.net> <87pq05mdqc.fsf@fleche.redhat.com> <83lias3ybi.fsf@gnu.org> <20130219162741.GA4493@host2.jankratochvil.net> <838v6kp4gu.fsf@gnu.org> <20130220084353.GA801@host2.jankratochvil.net> <83fw0qokfw.fsf@gnu.org> <20130404160915.GA11966@host2.jankratochvil.net> <83sj36fcxb.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83sj36fcxb.fsf@gnu.org> User-Agent: Mutt/1.5.21 (2010-09-15) X-IsSubscribed: yes X-SW-Source: 2013-04/txt/msg00111.txt.bz2 On Thu, 04 Apr 2013 19:01:04 +0200, Eli Zaretskii wrote: > These are the only 2 changes and the only comments I had, right? If > so, this is ready to go in, thanks. For gdbinit.5 it is true but in this patch I also added the gdb.1 and gdbserver.1 conversion (so that no *.[0-9] files are in the repository anymore). Sorry for not splitting it but you can follow the incremental diff below where the gdbinit.5 change is no longer visible. Thanks, Jan diff --git a/README.archer b/README.archer new file mode 100644 index 0000000..1723606 --- /dev/null +++ b/README.archer @@ -0,0 +1,2 @@ +Unify man pages into texinfo format: +https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=881892 diff --git a/gdb/Makefile.in b/gdb/Makefile.in index 47b4338..9a0a624 100644 --- a/gdb/Makefile.in +++ b/gdb/Makefile.in @@ -1019,11 +1019,6 @@ check//%: force info install-info clean-info dvi pdf install-pdf html install-html: force @$(MAKE) $(FLAGS_TO_PASS) DO=$@ "DODIRS=$(SUBDIRS)" subdir_do -gdb.z:gdb.1 - nroff -man $(srcdir)/gdb.1 | col -b > gdb.t - pack gdb.t ; rm -f gdb.t - mv gdb.t.z gdb.z - # Traditionally "install" depends on "all". But it may be useful # not to; for example, if the user has made some trivial change to a # source file and doesn't care about rebuilding or just wants to save the @@ -1043,10 +1038,6 @@ install-only: $(CONFIG_INSTALL) $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(bindir) ; \ $(INSTALL_PROGRAM) gdb$(EXEEXT) \ $(DESTDIR)$(bindir)/$$transformed_name$(EXEEXT) ; \ - $(SHELL) $(srcdir)/../mkinstalldirs \ - $(DESTDIR)$(man1dir) ; \ - $(INSTALL_DATA) $(srcdir)/gdb.1 \ - $(DESTDIR)$(man1dir)/$$transformed_name.1 ; \ $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(includedir)/gdb ; \ $(INSTALL_DATA) jit-reader.h $(DESTDIR)$(includedir)/gdb/jit-reader.h @$(MAKE) DO=install "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index 4572041..b016740 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -27,6 +27,7 @@ docdir = @docdir@ pdfdir = @pdfdir@ htmldir = @htmldir@ mandir = @mandir@ +man1dir = $(mandir)/man1 man5dir = $(mandir)/man5 SHELL = @SHELL@ @@ -170,14 +171,15 @@ MANCONF = -Dman TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl \ $(MAKEINFOFLAGS) $(MAKEINFO_EXTRA_FLAGS) +POD2MAN1 = pod2man --center="GNU Development Tools" \ + --release="gdb-$(VERSION)" --section=1 POD2MAN5 = pod2man --center="GNU Development Tools" \ --release="gdb-$(VERSION)" --section=5 # List of man pages generated from gdb.texi -MAN5S = \ - gdbinit.5 - -MANS = $(MAN5S) +MAN1S = gdb.1 gdbserver.1 +MAN5S = gdbinit.5 +MANS = $(MAN1S) $(MAN5S) #### Host, target, and site specific Makefile fragments come in here. ### @@ -262,7 +264,16 @@ install-pdf: $(PDFFILES) $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ done -install-man: install-man5 +install-man: install-man1 install-man5 + +install-man1: $(MAN1S) + test -z "$(man1dir)" || $(mkinstalldirs) "$(DESTDIR)$(man1dir)" + @list='$(MANS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=`echo $$p | sed -e 's|^.*/||'`; \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(man1dir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(man1dir)/$$f"; \ + done install-man5: $(MAN5S) test -z "$(man5dir)" || $(mkinstalldirs) "$(DESTDIR)$(man5dir)" @@ -273,7 +284,17 @@ install-man5: $(MAN5S) $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(man5dir)/$$f"; \ done -uninstall-man: uninstall-man5 +uninstall-man: uninstall-man1 uninstall-man5 + +uninstall-man1: + @test -n "$(man1dir)" || exit 0; \ + files=`{ l2='$(MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.1[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + test -z "$$files" || { \ + echo " ( cd '$(DESTDIR)$(man1dir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(man1dir)" && rm -f $$files; } uninstall-man5: @test -n "$(man5dir)" || exit 0; \ @@ -285,7 +306,7 @@ uninstall-man5: echo " ( cd '$(DESTDIR)$(man5dir)' && rm -f" $$files ")"; \ cd "$(DESTDIR)$(man5dir)" && rm -f $$files; } -STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf *.5 +STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf *.1 *.5 # Copy the object files from a particular stage into a subdirectory. stage1: force @@ -570,6 +591,20 @@ annotate/index.html: $(ANNOTATE_DOC_FILES) $(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/annotate.texinfo # Man pages +gdb.1: $(GDB_DOC_FILES) + touch $@ + -$(TEXI2POD) $(MANCONF) -Dgdb < gdb.texinfo > gdb.pod + -($(POD2MAN1) gdb.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \ + mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1) + rm -f gdb.pod + +gdbserver.1: $(GDB_DOC_FILES) + touch $@ + -$(TEXI2POD) $(MANCONF) -Dgdbserver < gdb.texinfo > gdbserver.pod + -($(POD2MAN1) gdbserver.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \ + mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1) + rm -f gdbserver.pod + gdbinit.5: $(GDB_DOC_FILES) touch $@ -$(TEXI2POD) $(MANCONF) -Dgdbinit < gdb.texinfo > gdbinit.pod @@ -607,6 +642,6 @@ distclean: clean maintainer-clean realclean: distclean rm -f GDBvn.texi *.info* *.dvi *.ps *.html *.pdf $(MANS) -install: install-info +install: install-info install-man -uninstall: uninstall-info +uninstall: uninstall-info uninstall-man diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 6bc3c06..eebfc85 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -41602,51 +41602,442 @@ switch (die->tag) @} @end smallexample -@include gpl.texi - @node Man Pages @appendix Manual pages @cindex Man pages @menu +* gdb man:: The GNU Debugger man page +* gdbserver man:: Remote Server for the GNU Debugger man page * gdbinit man:: gdbinit scripts @end menu -@node gdbinit man,,,Man Pages +@node gdb man +@heading gdb man + +@c man title gdb The GNU Debugger + +@c man begin SYNOPSIS gdb +gdb [@option{-help}] [@option{-nh}] [@option{-nx}] [@option{-q}] +[@option{-batch}] [@option{-cd=}@var{dir}] [@option{-f}] +[@option{-b}@w{ }@var{bps}] + [@option{-tty=}@var{dev}] [@option{-s} @var{symfile}] +[@option{-e}@w{ }@var{prog}] [@option{-se}@w{ }@var{prog}] +[@option{-c}@w{ }@var{core}] [@option{-x}@w{ }@var{cmds}] + [@option{-d}@w{ }@var{dir}] [@var{prog}|@var{core}|@var{procID}] +@c man end + +@c man begin DESCRIPTION gdb +The purpose of a debugger such as @value{GDBN} is to allow you to see what is +going on ``inside'' another program while it executes -- or what another +program was doing at the moment it crashed. + +@value{GDBN} can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + +@itemize @bullet +@item +Start your program, specifying anything that might affect its behavior. + +@item +Make your program stop on specified conditions. + +@item +Examine what has happened, when your program has stopped. + +@item +Change things in your program, so you can experiment with correcting the +effects of one bug and go on to learn about another. +@end itemize + +You can use @value{GDBN} to debug programs written in C, C++, and Modula-2. +Fortran support will be added when a GNU Fortran compiler is ready. + +GDB is invoked with the shell command @code{gdb}. Once started, it reads +commands from the terminal until you tell it to exit with the @value{GDBN} +command @code{quit}. You can get online help from @value{GDBN} itself +by using the command @code{help}. + +You can run @code{gdb} with no arguments or options; but the most +usual way to start @value{GDBN} is with one argument or two, specifying an +executable program as the argument: + +@smallexample +gdb program +@end smallexample + +You can also start with both an executable program and a core file specified: + +@smallexample +gdb program core +@end smallexample + +You can, instead, specify a process ID as a second argument, if you want +to debug a running process: + +@smallexample +gdb program 1234 +@end smallexample + +would attach @value{GDBN} to process @code{1234} (unless you also have a file +named @file{1234}; @value{GDBN} does check for a core file first). + +Here are some of the most frequently needed @value{GDBN} commands: + +@c pod2man highlights the right hand side of the @item lines. +@table @env +@item break [@var{file}:]@var{functiop} +Set a breakpoint at @var{function} (in @var{file}). + +@item run [@var{arglist}] +Start your program (with @var{arglist}, if specified). + +@item bt +Backtrace: display the program stack. + +@item print @var{expr} +Display the value of an expression. + +@item c +Continue running your program (after stopping, e.g. at a breakpoint). + +@item next +Execute next program line (after stopping); step @emph{over} any +function calls in the line. + +@item edit [@var{file}:]@var{function} +look at the program line where it is presently stopped. + +@item list [@var{file}:]@var{function} +type the text of the program in the vicinity of where it is presently stopped. + +@item step +Execute next program line (after stopping); step @emph{into} any +function calls in the line. + +@item help [@var{name}] +Show information about @value{GDBN} command @var{name}, or general information +about using @value{GDBN}. + +@item quit +Exit from @value{GDBN}. +@end table + +@ifset man +For full details on @value{GDBN}, +see @cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +by Richard M. Stallman and Roland H. Pesch. The same text is available online +as the @code{gdb} entry in the @code{info} program. +@end ifset +@c man end + +@c man begin OPTIONS gdb +Any arguments other than options specify an executable +file and core file (or process ID); that is, the first argument +encountered with no +associated option flag is equivalent to a @option{-se} option, and the second, +if any, is equivalent to a @option{-c} option if it's the name of a file. +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 @option{+} rather than @option{-}, though we illustrate the +more usual convention.) + +All the options and command line arguments you give are processed +in sequential order. The order makes a difference when the @option{-x} +option is used. + +@table @env +@item -help +@itemx -h +List all options, with brief explanations. + +@item -symbols=@var{file} +@itemx -s @var{file} +Read symbol table from file @var{file}. + +@item -write +Enable writing into executable and core files. + +@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 @value{GDBN} commands from file @var{file}. + +@item -ex @var{command} +Execute given @value{GDBN} @var{command}. + +@item -directory=@var{directory} +@itemx -d @var{directory} +Add @var{directory} to the path to search for source files. + +@item -nh +Do not execute commands from @file{~/.gdbinit}. + +@item -nx +@itemx -n +Do not execute commands from any @file{.gdbinit} initialization files. + +@item -quiet +@itemx -q +``Quiet''. Do not print the introductory and copyright messages. These +messages are also suppressed in batch mode. + +@item -batch +Run in batch mode. Exit with status @code{0} after processing all the command +files specified with @option{-x} (and @file{.gdbinit}, if not inhibited). +Exit with nonzero status if an error occurs in executing the @value{GDBN} +commands in the command files. + +Batch mode may be useful for running @value{GDBN} as a filter, for example to +download and run a program on another computer; in order to make this +more useful, the message + +@smallexample +Program exited normally. +@end smallexample + +(which is ordinarily issued whenever a program running under @value{GDBN} control +terminates) is not issued when running in batch mode. + +@item -cd=@var{directory} +Run @value{GDBN} using @var{directory} as its working directory, +instead of the current directory. + +@item -fullname +@itemx -f +Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells +@value{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-@value{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 @value{GDBN} for remote debugging. + +@item -tty=@var{device} +Run using @var{device} for your program's standard input and output. +@end table +@c man end + +@c man begin SEEALSO gdb +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gdbserver man +@heading gdbserver man + +@c man title gdbserver Remote Server for the GNU Debugger +@format +@c man begin SYNOPSIS gdbserver +gdbserver @var{tty} @var{prog} [@var{args}@dots{}] + +gdbserver @var{tty} --attach @var{PID} +@c man end +@end format + +@c man begin DESCRIPTION gdbserver +@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine +than the one which is running the program being debugged. + +@ifclear man +@subheading Usage (server (target) side) +@end ifclear +@ifset man +Usage (server (target) side): +@end ifset + +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, as +@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by +the @value{GDBN} running on the host system. + +To use the server, you log on to the target system, and run the @command{gdbserver} +program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of +your program, and (c) its arguments. The general syntax is: + +@smallexample +target> gdbserver COMM PROGRAM [ARGS ...] +@end smallexample + +For example, using a serial port, you might say: + +@smallexample +target> gdbserver /dev/com1 emacs foo.txt +@end smallexample + +This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and to +communicate with @value{GDBN} via /dev/com1. @command{gdbserver} now waits patiently for the +host @value{GDBN} to communicate with it. + +To use a TCP connection, you could say: + +@smallexample +target> gdbserver host:2345 emacs foo.txt +@end smallexample + +This says pretty much the same thing as the last example, except that we are +going to communicate with the host @value{GDBN} via TCP. The `host:2345' argument means +that we are expecting to see a TCP connection from `host' to local TCP port +2345. (Currently, the `host' part is ignored.) You can choose any number you +want for the port number as long as it does not conflict with any existing TCP +ports on the target system. This same port number must be used in the host +@value{GDBN}s `target remote' command, which will be described shortly. Note that if +you chose a port number that conflicts with another service, @command{gdbserver} will +print an error message and exit. + +On some targets, @command{gdbserver} can also attach to running programs. +This is accomplished via the --attach argument. The syntax is: + +@smallexample +target> gdbserver COMM --attach PID +@end smallexample + +PID is the process ID of a currently running process. It isn't +necessary to point @command{gdbserver} at a binary for the running process. + +@ifclear man +@subheading Usage (host side) +@end ifclear +@ifset man +Usage (host side): +@end ifset + +You need an unstripped copy of the target program on your host system, since +@value{GDBN} needs to examine it's symbol tables and such. Start up @value{GDBN} as you normally +would, with the target program as the first argument. (You may need to use the +--baud option if the serial line is running at anything except 9600 baud.) +Ie: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only +new command you need to know about is `target remote'. It's argument is either +a device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT +descriptor. For example: + +@smallexample +(gdb) target remote /dev/ttyb +@end smallexample + +communicates with the server via serial line /dev/ttyb, and: + +@smallexample +(gdb) target remote the-target:2345 +@end smallexample + +communicates via a TCP connection to port 2345 on host `the-target', where +you previously started up @command{gdbserver} with the same port number. Note that for +TCP connections, you must start up @command{gdbserver} prior to using the `target remote' +command, otherwise you may get an error that looks something like +`Connection refused'. +@c man end + +@c man begin OPTIONS gdbserver +You have to supply the name of the program to debug +and the tty to communicate on; the remote @value{GDBN} will do everything else. +Any remaining arguments will be passed to the program verbatim. +@c man end + +@c man begin SEEALSO gdbserver +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gdbinit man @heading gdbinit @c man title gdbinit GDB initialization scripts +@format @c man begin SYNOPSIS gdbinit -@table @env @ifset SYSTEM_GDBINIT -@itemx @value{SYSTEM_GDBINIT} +@value{SYSTEM_GDBINIT} @end ifset -@itemx ~/.gdbinit -@itemx ./.gdbinit -@end table + +~/.gdbinit + +./.gdbinit @c man end +@end format @c man begin DESCRIPTION gdbinit These files contain @value{GDBN} commands to automatically execute during @value{GDBN} startup. The lines of contents are canned sequences of commands, -described in the @value{GDBN} manual in node @code{Sequences}, accessible by -shell command @code{info -f gdb -n Sequences}. +described in +@ifset man +the @value{GDBN} manual in node @code{Sequences} +-- shell command @code{info -f gdb -n Sequences}. +@end ifset +@ifclear man +@ref{Sequences}. +@end ifclear -Please read more in the @value{GDBN} manual in node @code{Startup}, -accessible by shell command @code{info -f gdb -n Startup}. +Please read more in +@ifset man +the @value{GDBN} manual in node @code{Startup} +-- shell command @code{info -f gdb -n Startup}. +@end ifset +@ifclear man +@ref{Startup}. +@end ifclear @table @env @ifset SYSTEM_GDBINIT @item @value{SYSTEM_GDBINIT} @end ifset @ifclear SYSTEM_GDBINIT -@item (not enabled during @value{GDBN} compilation with @code{--with-system-gdbinit}) +@item (not enabled with @code{--with-system-gdbinit} during compilation) @end ifclear System-wide initialization file. It is executed unless user specified @value{GDBN} option @code{-nx} or @code{-n}. -See more in the @value{GDBN} manual in node @code{System-wide configuration}, -accessible by shell command @code{info -f gdb -n 'System-wide configuration'}. +See more in +@ifset man +the @value{GDBN} manual in node @code{System-wide configuration} +-- shell command @code{info -f gdb -n 'System-wide configuration'}. +@end ifset +@ifclear man +@ref{System-wide configuration}. +@end ifclear @item ~/.gdbinit User initialization file. It is executed unless user specified @@ -41655,17 +42046,37 @@ User initialization file. It is executed unless user specified @item ./.gdbinit Initialization file for current directory. It may need to be enabled with @value{GDBN} security command @code{set auto-load local-gdbinit}. -See more in the @value{GDBN} manual in node @code{Init File in the Current -Directory} - shell command -@code{info -f gdb -n 'Init File in the Current Directory'}. +See more in +@ifset man +the @value{GDBN} manual in node @code{Init File in the Current Directory} +-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}. +@end ifset +@ifclear man +@ref{Init File in the Current Directory}. +@end ifclear @end table @c man end -@ignore @c man begin SEEALSO gdbinit +@ifset man gdb(1), @code{info -f gdb -n Startup} + +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset @c man end -@end ignore + +@include gpl.texi @node GNU Free Documentation License @appendix GNU Free Documentation License diff --git a/gdb/gdb.1 b/gdb/gdb.1 deleted file mode 100644 index ec6c02a..0000000 --- a/gdb/gdb.1 +++ /dev/null @@ -1,403 +0,0 @@ -.\" Copyright (C) 1991-2013 Free Software Foundation, Inc. -.\" See section COPYING for conditions for redistribution -.\" $Id$ -.TH gdb 1 "22may2002" "GNU Tools" "GNU Tools" -.SH NAME -gdb \- The GNU Debugger -.SH SYNOPSIS -.na -.TP -.B gdb -.RB "[\|" \-help "\|]" -.RB "[\|" \-nh "\|]" -.RB "[\|" \-nx "\|]" -.RB "[\|" \-q "\|]" -.RB "[\|" \-batch "\|]" -.RB "[\|" \-cd=\c -.I dir\c -\|] -.RB "[\|" \-f "\|]" -.RB "[\|" "\-b\ "\c -.IR bps "\|]" -.RB "[\|" "\-tty="\c -.IR dev "\|]" -.RB "[\|" "\-s "\c -.I symfile\c -\&\|] -.RB "[\|" "\-e "\c -.I prog\c -\&\|] -.RB "[\|" "\-se "\c -.I prog\c -\&\|] -.RB "[\|" "\-c "\c -.I core\c -\&\|] -.RB "[\|" "\-x "\c -.I file\c -\&\|] -.RB "[\|" "\-ex "\c -.I cmd\c -\&\|] -.RB "[\|" "\-d "\c -.I dir\c -\&\|] -.RB "[\|" \c -.I prog\c -.RB "[\|" \c -.IR core \||\| procID\c -\&\|]\&\|] -.ad b -.SH DESCRIPTION -The purpose of a debugger such as GDB is to allow you to see what is -going on ``inside'' another program while it executes\(em\&or what another -program was doing at the moment it crashed. - -GDB can do four main kinds of things (plus other things in support of -these) to help you catch bugs in the act: - -.TP -\ \ \ \(bu -Start your program, specifying anything that might affect its behavior. - -.TP -\ \ \ \(bu -Make your program stop on specified conditions. - -.TP -\ \ \ \(bu -Examine what has happened, when your program has stopped. - -.TP -\ \ \ \(bu -Change things in your program, so you can experiment with correcting the -effects of one bug and go on to learn about another. -.PP - -You can use GDB to debug programs written in C, C++, and Modula-2. -Fortran support will be added when a GNU Fortran compiler is ready. - -GDB is invoked with the shell command \c -.B gdb\c -\&. Once started, it reads -commands from the terminal until you tell it to exit with the GDB -command \c -.B quit\c -\&. You can get online help from \c -.B gdb\c -\& itself -by using the command \c -.B help\c -\&. - -You can run \c -.B gdb\c -\& with no arguments or options; but the most -usual way to start GDB is with one argument or two, specifying an -executable program as the argument: -.sp -.br -gdb\ program -.br -.sp - -You can also start with both an executable program and a core file specified: -.sp -.br -gdb\ program\ core -.br -.sp - -You can, instead, specify a process ID as a second argument, if you want -to debug a running process: -.sp -.br -gdb\ program\ 1234 -.br -.sp - -would attach GDB to process \c -.B 1234\c -\& (unless you also have a file -named `\|\c -.B 1234\c -\&\|'; GDB does check for a core file first). - -Here are some of the most frequently needed GDB commands: -.TP -.B break \fR[\|\fIfile\fB:\fR\|]\fIfunction -\& -Set a breakpoint at \c -.I function\c -\& (in \c -.I file\c -\&). -.TP -.B run \fR[\|\fIarglist\fR\|] -Start your program (with \c -.I arglist\c -\&, if specified). -.TP -.B bt -Backtrace: display the program stack. -.TP -.BI print " expr"\c -\& -Display the value of an expression. -.TP -.B c -Continue running your program (after stopping, e.g. at a breakpoint). -.TP -.B next -Execute next program line (after stopping); step \c -.I over\c -\& any -function calls in the line. -.TP -.B edit \fR[\|\fIfile\fB:\fR\|]\fIfunction -look at the program line where it is presently stopped. -.TP -.B list \fR[\|\fIfile\fB:\fR\|]\fIfunction -type the text of the program in the vicinity of where it is presently stopped. -.TP -.B step -Execute next program line (after stopping); step \c -.I into\c -\& any -function calls in the line. -.TP -.B help \fR[\|\fIname\fR\|] -Show information about GDB command \c -.I name\c -\&, or general information -about using GDB. -.TP -.B quit -Exit from GDB. -.PP -For full details on GDB, see \c -.I -Using GDB: A Guide to the GNU Source-Level Debugger\c -\&, by Richard M. Stallman and Roland H. Pesch. The same text is available online -as the \c -.B gdb\c -\& entry in the \c -.B info\c -\& program. -.SH OPTIONS -Any arguments other than options specify an executable -file and core file (or process ID); that is, the first argument -encountered with no -associated option flag is equivalent to a `\|\c -.B \-se\c -\&\|' option, and the -second, if any, is equivalent to a `\|\c -.B \-c\c -\&\|' option if it's the name of a file. 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 `\|\c -.B +\c -\&\|' rather than `\|\c -.B \-\c -\&\|', though we illustrate the -more usual convention.) - -All the options and command line arguments you give are processed -in sequential order. The order makes a difference when the -`\|\c -.B \-x\c -\&\|' option is used. - -.TP -.B \-help -.TP -.B \-h -List all options, with brief explanations. - -.TP -.BI "\-symbols=" "file"\c -.TP -.BI "\-s " "file"\c -\& -Read symbol table from file \c -.I file\c -\&. - -.TP -.B \-write -Enable writing into executable and core files. - -.TP -.BI "\-exec=" "file"\c -.TP -.BI "\-e " "file"\c -\& -Use file \c -.I file\c -\& as the executable file to execute when -appropriate, and for examining pure data in conjunction with a core -dump. - -.TP -.BI "\-se=" "file"\c -\& -Read symbol table from file \c -.I file\c -\& and use it as the executable -file. - -.TP -.BI "\-core=" "file"\c -.TP -.BI "\-c " "file"\c -\& -Use file \c -.I file\c -\& as a core dump to examine. - -.TP -.BI "\-command=" "file"\c -.TP -.BI "\-x " "file"\c -\& -Execute GDB commands from file \c -.I file\c -\&. - -.TP -.BI "\-ex " "command"\c -\& -Execute given GDB \c -.I command\c -\&. - -.TP -.BI "\-directory=" "directory"\c -.TP -.BI "\-d " "directory"\c -\& -Add \c -.I directory\c -\& to the path to search for source files. -.PP - -.TP -.B \-nh -Do not execute commands from ~/.gdbinit. - -.TP -.B \-nx -.TP -.B \-n -Do not execute commands from any `\|\c -.B .gdbinit\c -\&\|' initialization files. - - -.TP -.B \-quiet -.TP -.B \-q -``Quiet''. Do not print the introductory and copyright messages. These -messages are also suppressed in batch mode. - -.TP -.B \-batch -Run in batch mode. Exit with status \c -.B 0\c -\& after processing all the command -files specified with `\|\c -.B \-x\c -\&\|' (and `\|\c -.B .gdbinit\c -\&\|', if not inhibited). -Exit with nonzero status if an error occurs in executing the GDB -commands in the command files. - -Batch mode may be useful for running GDB as a filter, for example to -download and run a program on another computer; in order to make this -more useful, the message -.sp -.br -Program\ exited\ normally. -.br -.sp - -(which is ordinarily issued whenever a program running under GDB control -terminates) is not issued when running in batch mode. - -.TP -.BI "\-cd=" "directory"\c -\& -Run GDB using \c -.I directory\c -\& as its working directory, -instead of the current directory. - -.TP -.B \-fullname -.TP -.B \-f -Emacs sets this option when it runs GDB as a subprocess. It tells GDB -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 `\|\c -.B \032\c -\&\|' characters, followed by the file name, line number -and character position separated by colons, and a newline. The -Emacs-to-GDB interface program uses the two `\|\c -.B \032\c -\&\|' characters as -a signal to display the source code for the frame. - -.TP -.BI "\-b " "bps"\c -\& -Set the line speed (baud rate or bits per second) of any serial -interface used by GDB for remote debugging. - -.TP -.BI "\-tty=" "device"\c -\& -Run using \c -.I device\c -\& for your program's standard input and output. -.PP - -.SH "SEE ALSO" -The full documentation for -.B gdb -is maintained as a Texinfo manual. If the -.B info -and -.B gdb -programs and GDB's Texinfo documentation are properly installed at -your site, the command -.IP -.B info gdb -.PP -should give you access to the complete manual. - -.I -Using GDB: A Guide to the GNU Source-Level Debugger\c -, Richard M. Stallman and Roland H. Pesch, July 1991. -.SH COPYING -Copyright (c) 1991, 2010 Free Software Foundation, Inc. -.PP -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. -.PP -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. -.PP -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the Free Software Foundation instead of in -the original English. diff --git a/gdb/gdbserver/Makefile.in b/gdb/gdbserver/Makefile.in index 08db2cc..ef839d3 100644 --- a/gdb/gdbserver/Makefile.in +++ b/gdb/gdbserver/Makefile.in @@ -252,8 +252,6 @@ install-only: fi; \ $(SHELL) $(srcdir)/../../mkinstalldirs $(DESTDIR)$(bindir); \ $(INSTALL_PROGRAM) gdbserver$(EXEEXT) $(DESTDIR)$(bindir)/$$n$(EXEEXT); \ - $(SHELL) $(srcdir)/../../mkinstalldirs $(DESTDIR)$(man1dir); \ - $(INSTALL_DATA) $(srcdir)/gdbserver.1 $(DESTDIR)$(man1dir)/$$n.1 @$(MAKE) $(FLAGS_TO_PASS) DO=$@ "DODIRS=$(SUBDIRS)" subdir_do uninstall: force diff --git a/gdb/gdbserver/gdbserver.1 b/gdb/gdbserver/gdbserver.1 deleted file mode 100644 index 59ed0bb..0000000 --- a/gdb/gdbserver/gdbserver.1 +++ /dev/null @@ -1,116 +0,0 @@ -.\" Copyright (C) 1993-2013 Free Software Foundation, Inc. -.\" See section COPYING for conditions for redistribution -.TH gdbserver 1 "2 November 1993" "Cygnus Support" "GNU Development Tools" -.SH NAME -gdbserver \- Remote Server for the GNU Debugger -.SH SYNOPSIS -.na -.TP -.B gdbserver -.RB tty -.RB prog -.RB "[\|" args... "\|]" -.PP -.B gdbserver -.RB tty -.B --attach -.RB PID -.ad b -.SH DESCRIPTION -GDBSERVER is a program that allows you to run GDB on a different machine -than the one which is running the program being debugged. - -Usage (server (target) side): - -First, you need to have a copy of the program you want to debug put onto -the target system. The program can be stripped to save space if needed, as -GDBserver doesn't care about symbols. All symbol handling is taken care of by -the GDB running on the host system. - -To use the server, you log on to the target system, and run the `gdbserver' -program. You must tell it (a) how to communicate with GDB, (b) the name of -your program, and (c) its arguments. The general syntax is: - - target> gdbserver COMM PROGRAM [ARGS ...] - -For example, using a serial port, you might say: - - target> gdbserver /dev/com1 emacs foo.txt - -This tells gdbserver to debug emacs with an argument of foo.txt, and to -communicate with GDB via /dev/com1. Gdbserver now waits patiently for the -host GDB to communicate with it. - -To use a TCP connection, you could say: - - target> gdbserver host:2345 emacs foo.txt - -This says pretty much the same thing as the last example, except that we are -going to communicate with the host GDB via TCP. The `host:2345' argument means -that we are expecting to see a TCP connection from `host' to local TCP port -2345. (Currently, the `host' part is ignored.) You can choose any number you -want for the port number as long as it does not conflict with any existing TCP -ports on the target system. This same port number must be used in the host -GDBs `target remote' command, which will be described shortly. Note that if -you chose a port number that conflicts with another service, gdbserver will -print an error message and exit. - -On some targets, gdbserver can also attach to running programs. -This is accomplished via the --attach argument. The syntax is: - - target> gdbserver COMM --attach PID - -PID is the process ID of a currently running process. It isn't -necessary to point gdbserver at a binary for the running process. - -Usage (host side): - -You need an unstripped copy of the target program on your host system, since -GDB needs to examine it's symbol tables and such. Start up GDB as you normally -would, with the target program as the first argument. (You may need to use the ---baud option if the serial line is running at anything except 9600 baud.) -Ie: `gdb TARGET-PROG', or `gdb --baud BAUD TARGET-PROG'. After that, the only -new command you need to know about is `target remote'. It's argument is either -a device name (usually a serial device, like `/dev/ttyb'), or a HOST:PORT -descriptor. For example: - - (gdb) target remote /dev/ttyb - -communicates with the server via serial line /dev/ttyb, and: - - (gdb) target remote the-target:2345 - -communicates via a TCP connection to port 2345 on host `the-target', where -you previously started up gdbserver with the same port number. Note that for -TCP connections, you must start up gdbserver prior to using the `target remote' -command, otherwise you may get an error that looks something like -`Connection refused'. -.SH OPTIONS -You have to supply the name of the program to debug -and the tty to communicate on; the remote GDB will do everything else. -Any remaining arguments will be passed to the program verbatim. -.SH "SEE ALSO" -.RB "`\|" gdb "\|'" -entry in -.B info\c -\&; -.I -Using GDB: A Guide to the GNU Source-Level Debugger\c -, Richard M. Stallman and Roland H. Pesch, July 1991. -.SH COPYING -Copyright (c) 1993 Free Software Foundation, Inc. -.PP -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. -.PP -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. -.PP -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the Free Software Foundation instead of in -the original English.