http://sourceware.org/ml/gdb-cvs/2013-04/msg00056.html ### src/gdb/ChangeLog 2013/04/05 19:17:15 1.15370 ### src/gdb/ChangeLog 2013/04/05 20:01:32 1.15371 ## -1,5 +1,12 @@ 2013-04-05 Jan Kratochvil + Convert man pages to texinfo, new gdbinit.5 texinfo page. + * Makefile.in (gdb.z): Remove. + (install-only): Remove $(man1dir) and gdb.1 installation. + * gdb.1: Remove. + +2013-04-05 Jan Kratochvil + Fix compatibility with Linux kernel 3.8.3. * linux-tdep.c (linux_find_memory_regions_full): Move variable number to more inner block. Remove parsing of NUMBER from outer block. --- src/gdb/Makefile.in 2013/04/05 13:24:24 1.1246 +++ src/gdb/Makefile.in 2013/04/05 20:01:33 1.1247 @@ -1019,11 +1019,6 @@ 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 @@ $(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 ### src/gdb/doc/ChangeLog 2013/04/02 17:52:08 1.1432 ### src/gdb/doc/ChangeLog 2013/04/05 20:01:33 1.1433 ## -1,3 +1,22 @@ +2013-04-05 Jan Kratochvil + + Convert man pages to texinfo, new gdbinit.5 texinfo page. + * Makefile.in (mandir, man1dir, man5dir, SYSTEM_GDBINIT, MANCONF, + (TEXI2POD, POD2MAN1, POD2MAN5, MAN1S, MAN5S, MANS, man): New. + (diststuff): Add man. + (install-man, install-man1, install-man5, uninstall-man, uninstall-man1) + (uninstall-man5): New. + (STAGESTUFF): Add *.1 and *.5. + (GDBvn.texi): Add SYSTEM_GDBINIT. + (gdb.1, gdbserver.1, gdbinit.5): New. + (maintainer-clean realclean): Add $(MANS). + (install): Add install-man. + (uninstall): Add uninstall-man. + * gdb.texinfo (@include gdb-cfg.texi): Wrap it by @c man begin INCLUDE. + (@copying): Wrap it by @c man begin COPYRIGHT. + (Top): Add Man Pages. + (Man Pages, gdb man, gdbserver man, gdbinit man): New. + 2013-04-02 Pedro Alves * gdb.texinfo (Debugging Output): Document "set/show debug --- src/gdb/doc/Makefile.in 2013/01/01 06:32:56 1.57 +++ src/gdb/doc/Makefile.in 2013/04/05 20:01:33 1.58 @@ -26,6 +26,9 @@ docdir = @docdir@ pdfdir = @pdfdir@ htmldir = @htmldir@ +mandir = @mandir@ +man1dir = $(mandir)/man1 +man5dir = $(mandir)/man5 SHELL = @SHELL@ @@ -35,6 +38,8 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_DATA = @INSTALL_DATA@ +SYSTEM_GDBINIT = @SYSTEM_GDBINIT@ + mkinstalldirs = $(SHELL) $(srcdir)/../../mkinstalldirs # main GDB source directory @@ -160,6 +165,22 @@ $(ANNOTATE_DOC_SOURCE_INCLUDES) \ $(ANNOTATE_DOC_BUILD_INCLUDES) +# Options to extract the man page from gdb.texinfo +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 +MAN1S = gdb.1 gdbserver.1 +MAN5S = gdbinit.5 +MANS = $(MAN1S) $(MAN5S) + #### Host, target, and site specific Makefile fragments come in here. ### @@ -170,8 +191,9 @@ ps: gdb.ps gdbint.ps stabs.ps refcard.ps annotate.ps html: $(HTMLFILES) pdf: $(PDFFILES) +man: $(MANS) all-doc: info dvi ps # pdf -diststuff: info +diststuff: info man rm -f gdb-cfg.texi GDBvn.texi install-info: $(INFO_DEPS) @@ -242,7 +264,49 @@ $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ done -STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf +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)" + @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)$(man5dir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(man5dir)/$$f"; \ + done + +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; \ + files=`{ l2='$(MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.5[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + test -z "$$files" || { \ + echo " ( cd '$(DESTDIR)$(man5dir)' && rm -f" $$files ")"; \ + cd "$(DESTDIR)$(man5dir)" && rm -f $$files; } + +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 @@ -313,6 +377,9 @@ if test -z "$(READLINE_TEXI_INCFLAG)"; then \ echo "@set SYSTEM_READLINE" >> ./GDBvn.new; \ fi + if [ -n "$(SYSTEM_GDBINIT)" ]; then \ + echo "@set SYSTEM_GDBINIT $(SYSTEM_GDBINIT)" >> ./GDBvn.new; \ + fi mv GDBvn.new GDBvn.texi # Updated atomically @@ -523,6 +590,28 @@ 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 + -($(POD2MAN5) gdbinit.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \ + mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1) + rm -f gdbinit.pod + force: Makefile: Makefile.in $(host_makefile_frag) ../config.status @@ -551,8 +640,8 @@ # "clean" or "distclean". Use maintainer-clean to remove them. maintainer-clean realclean: distclean - rm -f GDBvn.texi *.info* *.dvi *.ps *.html *.pdf + 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 --- src/gdb/doc/gdb.texinfo 2013/04/02 17:52:08 1.1069 +++ src/gdb/doc/gdb.texinfo 2013/04/05 20:01:33 1.1070 @@ -6,7 +6,9 @@ @c of @set vars. However, you can override filename with makeinfo -o. @setfilename gdb.info @c +@c man begin INCLUDE @include gdb-cfg.texi +@c man end @c @settitle Debugging with @value{GDBN} @setchapternewpage odd @@ -46,6 +48,7 @@ @end direntry @copying +@c man begin COPYRIGHT Copyright @copyright{} 1988-2013 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -58,6 +61,7 @@ (a) The FSF's Back-Cover Text is: ``You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.'' +@c man end @end copying @ifnottex @@ -179,6 +183,7 @@ the operating system * Trace File Format:: GDB trace file format * Index Section Format:: .gdb_index section format +* Man Pages:: Manual pages * Copying:: GNU General Public License says how you can copy and share GDB * GNU Free Documentation License:: The license for this documentation @@ -41597,6 +41602,497 @@ @} @end smallexample +@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 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@t{++}, and Modula-2. +Fortran support will be added when a GNU Fortran compiler is ready. + +@value{GDBN} 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 + +@noindent +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 + +@noindent +(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 + +@noindent +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 @var{comm} @var{program} [@var{args} ...] +@end smallexample + +For example, using a serial port, you might say: + +@smallexample +@ifset man +@c @file would wrap it as F. +target> gdbserver /dev/com1 emacs foo.txt +@end ifset +@ifclear man +target> gdbserver @file{/dev/com1} emacs foo.txt +@end ifclear +@end smallexample + +This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and +to communicate with @value{GDBN} via @file{/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 @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means +that we are expecting to see a TCP connection from @code{host} to local TCP port +2345. (Currently, the @code{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 @code{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 @option{--attach} argument. The syntax is: + +@smallexample +target> gdbserver @var{comm} --attach @var{pid} +@end smallexample + +@var{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 +@option{--baud} option if the serial line is running at anything except 9600 baud.) +That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only +new command you need to know about is @code{target remote}. It's argument is either +a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT} +descriptor. For example: + +@smallexample +@ifset man +@c @file would wrap it as F. +(gdb) target remote /dev/ttyb +@end ifset +@ifclear man +(gdb) target remote @file{/dev/ttyb} +@end ifclear +@end smallexample + +@noindent +communicates with the server via serial line @file{/dev/ttyb}, and: + +@smallexample +(gdb) target remote the-target:2345 +@end smallexample + +@noindent +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 +@ifset SYSTEM_GDBINIT +@value{SYSTEM_GDBINIT} +@end ifset + +~/.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 +@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 +@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 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 +@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 +@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}. + +@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 +@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 + +@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 + @include gpl.texi @node GNU Free Documentation License ### src/gdb/gdbserver/ChangeLog 2013/03/22 14:52:26 1.702 ### src/gdb/gdbserver/ChangeLog 2013/04/05 20:01:33 1.703 ## -1,3 +1,10 @@ +2013-04-05 Jan Kratochvil + + Convert man pages to texinfo, new gdbinit.5 texinfo page. + * Makefile.in (install-only): Remove $(man1dir) and gdbserver.1 + installation. + * gdbserver.1: Remove. + 2013-03-22 Pedro Alves * linux-low.c (handle_extended_wait): Don't call --- src/gdb/gdbserver/Makefile.in 2013/03/15 17:30:27 1.145 +++ src/gdb/gdbserver/Makefile.in 2013/04/05 20:01:33 1.146 @@ -252,8 +252,6 @@ 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 http://sourceware.org/ml/gdb-cvs/2013-04/msg00057.html ### src/gdb/doc/ChangeLog 2013/04/05 20:01:33 1.1433 ### src/gdb/doc/ChangeLog 2013/04/05 20:02:58 1.1434 ## -1,5 +1,10 @@ 2013-04-05 Jan Kratochvil + * gdb.texinfo (gdb man): Mention option -p. Include Fortran to + the list of supported languages. + +2013-04-05 Jan Kratochvil + Convert man pages to texinfo, new gdbinit.5 texinfo page. * Makefile.in (mandir, man1dir, man5dir, SYSTEM_GDBINIT, MANCONF, (TEXI2POD, POD2MAN1, POD2MAN5, MAN1S, MAN5S, MANS, man): New. --- src/gdb/doc/gdb.texinfo 2013/04/05 20:01:33 1.1070 +++ src/gdb/doc/gdb.texinfo 2013/04/05 20:02:58 1.1071 @@ -41623,8 +41623,9 @@ [@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}] +[@option{-c}@w{ }@var{core}] [@option{-p}@w{ }@var{procID}] + [@option{-x}@w{ }@var{cmds}] [@option{-d}@w{ }@var{dir}] +[@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}] @c man end @c man begin DESCRIPTION gdb @@ -41650,8 +41651,8 @@ 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@t{++}, and Modula-2. -Fortran support will be added when a GNU Fortran compiler is ready. +You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and +Modula-2. @value{GDBN} 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} @@ -41677,11 +41678,13 @@ @smallexample gdb program 1234 +gdb -p 1234 @end smallexample @noindent 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). +With option @option{-p} you can omit the @var{program} filename. Here are some of the most frequently needed @value{GDBN} commands: http://sourceware.org/ml/gdb-cvs/2013-04/msg00064.html ### src/gdb/doc/ChangeLog 2013/04/05 20:02:58 1.1434 ### src/gdb/doc/ChangeLog 2013/04/06 08:58:53 1.1435 ## -1,3 +1,11 @@ +2013-04-06 Jan Kratochvil + Eli Zaretskii + + * gdb.texinfo (gdbserver man): Rename tty to comm. Swap --attach + parameters order. Remove "On some targets" for --attach. Document the + --multi parameter and extended-remote command. Document all the + options. + 2013-04-05 Jan Kratochvil * gdb.texinfo (gdb man): Mention option -p. Include Fortran to --- src/gdb/doc/gdb.texinfo 2013/04/05 20:02:58 1.1071 +++ src/gdb/doc/gdb.texinfo 2013/04/06 08:58:53 1.1072 @@ -41867,9 +41867,11 @@ @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{comm} @var{prog} [@var{args}@dots{}] -gdbserver @var{tty} --attach @var{PID} +gdbserver --attach @var{comm} @var{pid} + +gdbserver --multi @var{comm} @c man end @end format @@ -41929,16 +41931,25 @@ 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. +@command{gdbserver} can also attach to running programs. This is accomplished via the @option{--attach} argument. The syntax is: @smallexample -target> gdbserver @var{comm} --attach @var{pid} +target> gdbserver --attach @var{comm} @var{pid} @end smallexample @var{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. +To start @code{gdbserver} without supplying an initial command to run +or process ID to attach, use the @option{--multi} command line option. +In such case you should connect using @kbd{target extended-remote} to start +the program you want to debug. + +@smallexample +target> gdbserver --multi @var{comm} +@end smallexample + @ifclear man @subheading Usage (host side) @end ifclear @@ -41951,7 +41962,8 @@ would, with the target program as the first argument. (You may need to use the @option{--baud} option if the serial line is running at anything except 9600 baud.) That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only -new command you need to know about is @code{target remote}. It's argument is either +new command you need to know about is @code{target remote} +(or @code{target extended-remote}). Its argument is either a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT} descriptor. For example: @@ -41978,12 +41990,131 @@ 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'. + +@command{gdbserver} can also debug multiple inferiors at once, +described in +@ifset man +the @value{GDBN} manual in node @code{Inferiors and Programs} +-- shell command @code{info -f gdb -n 'Inferiors and Programs'}. +@end ifset +@ifclear man +@ref{Inferiors and Programs}. +@end ifclear +In such case use the @code{extended-remote} @value{GDBN} command variant: + +@smallexample +(gdb) target extended-remote the-target:2345 +@end smallexample + +The @command{gdbserver} option @option{--multi} may or may not be used in such +case. @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. +There are three different modes for invoking @command{gdbserver}: + +@itemize @bullet + +@item +Debug a specific program specified by its program name: + +@smallexample +gdbserver @var{comm} @var{prog} [@var{args}@dots{}] +@end smallexample + +The @var{comm} parameter specifies how should the server communicate +with @value{GDBN}; it is either a device name (to use a serial line), +a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use +stdin/stdout of @code{gdbserver}. Specify the name of the program to +debug in @var{prog}. Any remaining arguments will be passed to the +program verbatim. When the program exits, @value{GDBN} will close the +connection, and @code{gdbserver} will exit. + +@item +Debug a specific program by specifying the process ID of a running +program: + +@smallexample +gdbserver --attach @var{comm} @var{pid} +@end smallexample + +The @var{comm} parameter is as described above. Supply the process ID +of a running program in @var{pid}; @value{GDBN} will do everything +else. Like with the previous mode, when the process @var{pid} exits, +@value{GDBN} will close the connection, and @code{gdbserver} will exit. + +@item +Multi-process mode -- debug more than one program/process: + +@smallexample +gdbserver --multi @var{comm} +@end smallexample + +In this mode, @value{GDBN} can instruct @command{gdbserver} which +command(s) to run. Unlike the other 2 modes, @value{GDBN} will not +close the connection when a process being debugged exits, so you can +debug several processes in the same session. +@end itemize + +In each of the modes you may specify these options: + +@table @env + +@item --help +List all options, with brief explanations. + +@item --version +This option causes @command{gdbserver} to print its version number and exit. + +@item --attach +@command{gdbserver} will attach to a running program. The syntax is: + +@smallexample +target> gdbserver --attach @var{comm} @var{pid} +@end smallexample + +@var{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. + +@item --multi +To start @code{gdbserver} without supplying an initial command to run +or process ID to attach, use this command line option. +Then you can connect using @kbd{target extended-remote} and start +the program you want to debug. The syntax is: + +@smallexample +target> gdbserver --multi @var{comm} +@end smallexample + +@item --debug +Instruct @code{gdbserver} to display extra status information about the debugging +process. +This option is intended for @code{gdbserver} development and for bug reports to +the developers. + +@item --remote-debug +Instruct @code{gdbserver} to display remote protocol debug output. +This option is intended for @code{gdbserver} development and for bug reports to +the developers. + +@item --wrapper +Specify a wrapper to launch programs +for debugging. The option should be followed by the name of the +wrapper, then any command-line arguments to pass to the wrapper, then +@kbd{--} indicating the end of the wrapper arguments. + +@item --once +By default, @command{gdbserver} keeps the listening TCP port open, so that +additional connections are possible. However, if you start @code{gdbserver} +with the @option{--once} option, it will stop listening for any further +connection attempts after connecting to the first @value{GDBN} session. + +@c --disable-packet is not documented for users. + +@c --disable-randomization and --no-disable-randomization are superseded by +@c QDisableRandomization. + +@end table @c man end @c man begin SEEALSO gdbserver http://sourceware.org/ml/gdb-cvs/2013-04/msg00065.html ### src/gdb/doc/ChangeLog 2013/04/06 08:58:53 1.1435 ### src/gdb/doc/ChangeLog 2013/04/06 15:52:06 1.1436 ## -1,4 +1,8 @@ 2013-04-06 Jan Kratochvil + + * Makefile.in (POD2MAN1, POD2MAN5): Replace $(VERSION) by ../version.in. + +2013-04-06 Jan Kratochvil Eli Zaretskii * gdb.texinfo (gdbserver man): Rename tty to comm. Swap --attach --- src/gdb/doc/Makefile.in 2013/04/05 20:01:33 1.58 +++ src/gdb/doc/Makefile.in 2013/04/06 15:52:06 1.59 @@ -172,9 +172,9 @@ $(MAKEINFOFLAGS) $(MAKEINFO_EXTRA_FLAGS) POD2MAN1 = pod2man --center="GNU Development Tools" \ - --release="gdb-$(VERSION)" --section=1 + --release="gdb-`sed q $(srcdir)/../version.in`" --section=1 POD2MAN5 = pod2man --center="GNU Development Tools" \ - --release="gdb-$(VERSION)" --section=5 + --release="gdb-`sed q $(srcdir)/../version.in`" --section=5 # List of man pages generated from gdb.texi MAN1S = gdb.1 gdbserver.1 http://sourceware.org/ml/gdb-cvs/2013-04/msg00068.html ### src/gdb/gdbserver/ChangeLog 2013/04/05 20:01:33 1.703 ### src/gdb/gdbserver/ChangeLog 2013/04/07 05:53:21 1.704 ## -1,3 +1,7 @@ +2013-04-07 Jan Kratochvil + + * Makefile.in (install-only): Fix make install regression. + 2013-04-05 Jan Kratochvil Convert man pages to texinfo, new gdbinit.5 texinfo page. --- src/gdb/gdbserver/Makefile.in 2013/04/05 20:01:33 1.146 +++ src/gdb/gdbserver/Makefile.in 2013/04/07 05:53:22 1.147 @@ -251,7 +251,7 @@ $(INSTALL_PROGRAM) $(IPA_LIB) $(DESTDIR)$(libdir)/$(IPA_LIB); \ fi; \ $(SHELL) $(srcdir)/../../mkinstalldirs $(DESTDIR)$(bindir); \ - $(INSTALL_PROGRAM) gdbserver$(EXEEXT) $(DESTDIR)$(bindir)/$$n$(EXEEXT); \ + $(INSTALL_PROGRAM) gdbserver$(EXEEXT) $(DESTDIR)$(bindir)/$$n$(EXEEXT) @$(MAKE) $(FLAGS_TO_PASS) DO=$@ "DODIRS=$(SUBDIRS)" subdir_do uninstall: force http://sourceware.org/ml/gdb-cvs/2013-04/msg00069.html ### src/gdb/doc/ChangeLog 2013/04/06 15:52:06 1.1436 ### src/gdb/doc/ChangeLog 2013/04/07 06:04:58 1.1437 ## -2,6 +2,9 @@ * Makefile.in (POD2MAN1, POD2MAN5): Replace $(VERSION) by ../version.in. + * Makefile.in (install-man1, install-man5, uninstall-man1) + (uninstall-man5): Replace $(MANS) by $(MAN1S) and $(MAN5S) respectively. + 2013-04-06 Jan Kratochvil Eli Zaretskii --- src/gdb/doc/Makefile.in 2013/04/06 15:52:06 1.59 +++ src/gdb/doc/Makefile.in 2013/04/07 06:04:58 1.60 @@ -268,7 +268,7 @@ install-man1: $(MAN1S) test -z "$(man1dir)" || $(mkinstalldirs) "$(DESTDIR)$(man1dir)" - @list='$(MANS)'; for p in $$list; do \ + @list='$(MAN1S)'; 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'"; \ @@ -277,7 +277,7 @@ install-man5: $(MAN5S) test -z "$(man5dir)" || $(mkinstalldirs) "$(DESTDIR)$(man5dir)" - @list='$(MANS)'; for p in $$list; do \ + @list='$(MAN5S)'; 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)$(man5dir)/$$f'"; \ @@ -288,7 +288,7 @@ uninstall-man1: @test -n "$(man1dir)" || exit 0; \ - files=`{ l2='$(MANS)'; for i in $$l2; do echo "$$i"; done | \ + files=`{ l2='$(MAN1S)'; 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,.,'`; \ @@ -298,7 +298,7 @@ uninstall-man5: @test -n "$(man5dir)" || exit 0; \ - files=`{ l2='$(MANS)'; for i in $$l2; do echo "$$i"; done | \ + files=`{ l2='$(MAN5S)'; for i in $$l2; do echo "$$i"; done | \ sed -n '/\.5[a-z]*$$/p'; \ } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \ -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ http://sourceware.org/ml/gdb-cvs/2013-04/msg00070.html ### src/gdb/doc/ChangeLog 2013/04/07 06:04:58 1.1437 ### src/gdb/doc/ChangeLog 2013/04/07 06:20:19 1.1438 ## -5,6 +5,8 @@ * Makefile.in (install-man1, install-man5, uninstall-man1) (uninstall-man5): Replace $(MANS) by $(MAN1S) and $(MAN5S) respectively. + * Makefile.in (gdb.1, gdbserver.1, gdbinit.5): Use $(srcdir). + 2013-04-06 Jan Kratochvil Eli Zaretskii --- src/gdb/doc/Makefile.in 2013/04/07 06:04:58 1.60 +++ src/gdb/doc/Makefile.in 2013/04/07 06:20:19 1.61 @@ -593,21 +593,21 @@ # Man pages gdb.1: $(GDB_DOC_FILES) touch $@ - -$(TEXI2POD) $(MANCONF) -Dgdb < gdb.texinfo > gdb.pod + -$(TEXI2POD) $(MANCONF) -Dgdb < $(srcdir)/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 + -$(TEXI2POD) $(MANCONF) -Dgdbserver < $(srcdir)/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 + -$(TEXI2POD) $(MANCONF) -Dgdbinit < $(srcdir)/gdb.texinfo > gdbinit.pod -($(POD2MAN5) gdbinit.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \ mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1) rm -f gdbinit.pod