From patchwork Wed Jun 11 11:39:38 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pedro Alves X-Patchwork-Id: 1434 Received: (qmail 22155 invoked by alias); 11 Jun 2014 11:39:48 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 22140 invoked by uid 89); 11 Jun 2014 11:39:46 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.2 required=5.0 tests=AWL, BAYES_00, RP_MATCHES_RCVD, SPF_HELO_PASS, SPF_PASS autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 11 Jun 2014 11:39:44 +0000 Received: from int-mx14.intmail.prod.int.phx2.redhat.com (int-mx14.intmail.prod.int.phx2.redhat.com [10.5.11.27]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s5BBde97020639 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 11 Jun 2014 07:39:41 -0400 Received: from [127.0.0.1] (ovpn01.gateway.prod.ext.ams2.redhat.com [10.39.146.11]) by int-mx14.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s5BBdc7H031027; Wed, 11 Jun 2014 07:39:39 -0400 Message-ID: <53983FFA.6020909@redhat.com> Date: Wed, 11 Jun 2014 12:39:38 +0100 From: Pedro Alves User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.5.0 MIME-Version: 1.0 To: Eli Zaretskii , Mingjie Xing CC: gdb-patches@sourceware.org Subject: Re: [patch] Share options between info and man page References: <831tuy2kzi.fsf@gnu.org> <83ioo91nnk.fsf@gnu.org> <8338fc1wed.fsf@gnu.org> In-Reply-To: <8338fc1wed.fsf@gnu.org> On 06/10/2014 06:56 PM, Eli Zaretskii wrote: > Thanks. This looks good to me. If no one objects, it should go in > soon. I applied the patch locally, and noticed some things misrendered in the new man page, like, options are now listed with double quotes instead of being highlighted. E.g.: "-help" "-h" This one is preexisting, but note "C@t{++}" in: "You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2." This sentence seems to be out of place: "You can run GDB in various alternative modes---for example, in batch mode or quiet mode." Not sure, but "---" might be misrendered too. This incomplete sentence appears, seemingly trying to refer to a chapter in the manual: " For further documentation on startup processing, For documentation on how to write command files," At this point, I generated a diff of the old/new man pages, in plain text, with: $ man ./gdb.1 > gdb.1.txt $ man ./gdb.1.new > gdb.1.new.txt $ diff -up gdb.1.txt gdb.1.new.txt I think that's helpful to review this. The result is below. Seems there are other odd things in there, like "GDB/MI INTERFACE" in all caps? --- gdb.1.txt 2014-06-11 12:27:00.525999781 +0100 +++ gdb.1.new.txt 2014-06-11 12:27:09.823025888 +0100 @@ -83,56 +83,104 @@ DESCRIPTION as the "gdb" entry in the "info" program. 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 -se option, and the second, if any, is equivalent to a -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 + rather than -, though we illustrate the more usual convention.) + When GDB starts, it reads any arguments other than options as specifying an executable file and core file (or process ID). This is the same as if the arguments + were specified by the -se and -c (or -p) options respectively. (GDB reads the first argument that does not have an associated option flag as equivalent to the + -se option followed by that argument; and the second argument that does not have an associated option flag, if any, as equivalent to the -c/-p option followed + by that argument.) If the second argument begins with a decimal digit, GDB will first attempt to attach to it as a process, and if that fails, attempt to open + it as a corefile. If you have a corefile whose name begins with a digit, you can prevent GDB from treating it as a pid by prefixing it with ./, e.g. ./12345. + + If GDB has not been configured to included core file support, such as for most embedded targets, then it will complain about a second argument and ignore it. + + Many options have both long and short forms; both are shown in the following list. GDB also recognizes the long forms 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 -- rather than -, 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 -x option is used. - -help - -h List all options, with brief explanations. + "-help" + "-h" + List all options, with brief explanations. - -symbols=file - -s file + "-symbols file" + "-s file" Read symbol table from file file. - -write - Enable writing into executable and core files. - - -exec=file - -e file + "-exec file" + "-e file" Use file file as the executable file to execute when appropriate, and for examining pure data in conjunction with a core dump. - -se=file + "-se file" Read symbol table from file file and use it as the executable file. - -core=file - -c file + "-core file" + "-c file" Use file file as a core dump to examine. - -command=file - -x file - Execute GDB commands from file file. + "-pid number" + "-p number" + Connect to process ID number, as with the "attach" command. + + "-command file" + "-x file" + Execute commands from file file. The contents of this file is evaluated exactly as the "source" command would. + + "-eval-command command" + "-ex command" + Execute a single GDB command. + + This option may be used multiple times to call multiple commands. It may also be interleaved with -command as required. + + gdb -ex 'target sim' -ex 'load' \ + -x setbreakpoints -ex 'run' a.out + + "-init-command file" + "-ix file" + Execute commands from file file before loading the inferior (but after loading gdbinit files). + + "-init-eval-command command" + "-iex command" + Execute a single GDB command before loading the inferior (but after loading gdbinit files). + + "-directory directory" + "-d directory" + Add directory to the path to search for source and script files. - -ex command - Execute given GDB command. + "-r" + "-readnow" + Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed. This makes startup + slower, but makes future operations faster. - -directory=directory - -d directory - Add directory to the path to search for source files. + You can run GDB in various alternative modes---for example, in batch mode or quiet mode. - -nh Do not execute commands from ~/.gdbinit. + "-nx" + "-n" + Do not execute commands found in any initialization file. There are three init files, loaded in the following order: - -nx - -n Do not execute commands from any .gdbinit initialization files. + "system.gdbinit" + This is the system-wide init file. Its location is specified with the "--with-system-gdbinit" configure option. It is loaded first when GDB starts, + before command line options have been processed. - -quiet - -q "Quiet". Do not print the introductory and copyright messages. These messages are also suppressed in batch mode. + "~/.gdbinit" + This is the init file in your home directory. It is loaded next, after system.gdbinit, and before command options have been processed. - -batch - Run in batch mode. Exit with status 0 after processing all the command files specified with -x (and .gdbinit, if not inhibited). Exit with nonzero status - if an error occurs in executing the GDB commands in the command files. + "./.gdbinit" + This is the init file in the current directory. It is loaded last, after command line options other than "-x" and "-ex" have been processed. Command + line options "-x" and "-ex" are processed last, after ./.gdbinit has been loaded. + + For further documentation on startup processing, For documentation on how to write command files, + + "-nh" + Do not execute commands found in ~/.gdbinit, the init file in your home directory. + + "-quiet" + "-silent" + "-q" + "Quiet". Do not print the introductory and copyright messages. These messages are also suppressed in batch mode. + + "-batch" + Run in batch mode. Exit with status 0 after processing all the command files specified with -x (and all commands from initialization files, if not + inhibited with -n). Exit with nonzero status if an error occurs in executing the GDB commands in the command files. Batch mode also disables pagination, + sets unlimited terminal width and height @pxref{Screen Size}, and acts as if "set confirm off" were in effect. 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 @@ -141,21 +189,95 @@ OPTIONS (which is ordinarily issued whenever a program running under GDB control terminates) is not issued when running in batch mode. - -cd=directory + "-batch-silent" + Run in batch mode exactly like -batch, but totally silently. All GDB output to "stdout" is prevented ("stderr" is unaffected). This is much quieter than + -silent and would be useless for an interactive session. + + This is particularly useful when using targets that give Loading section messages, for example. + + Note that targets that give their output via GDB, as opposed to writing directly to "stdout", will also be made silent. + + "-return-child-result" + The return code from GDB will be the return code from the child process (the process being debugged), with the following exceptions: + + o GDB exits abnormally. E.g., due to an incorrect argument or an internal error. In this case the exit code is the same as it would have been without + -return-child-result. + + o The user quits with an explicit value. E.g., quit 1. + + o The child process never runs, or is not allowed to terminate, in which case the exit code will be -1. + + This option is useful in conjunction with -batch or -batch-silent, when GDB is being used as a remote program loader or simulator interface. + + "-nowindows" + "-nw" + "No windows". If GDB comes with a graphical user interface (GUI) built in, then this option tells GDB to only use the command-line interface. If no GUI is + available, this option has no effect. + + "-windows" + "-w" + If GDB includes a GUI, then this option requires it to be used if possible. + + "-cd directory" Run GDB using directory as its working directory, instead of the current directory. - -fullname - -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 \032 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 \032 characters as a signal to - display the source code for the frame. + "-data-directory directory" + "-D directory" + Run GDB using directory as its data directory. The data directory is where GDB searches for its auxiliary files. + + "-fullname" + "-f" + GNU 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 your program stops). This recognizable format looks like two \032 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 \032 characters as a + signal to display the source code for the frame. + + "-annotate level" + This option sets the annotation level inside GDB. Its effect is identical to using set annotate level. The annotation level controls how much information + GDB prints together with its prompt, values of expressions, source lines, and other types of output. Level 0 is the normal, level 1 is for use when GDB is + run as a subprocess of GNU Emacs, level 3 is the maximum annotation suitable for programs that control GDB, and level 2 has been deprecated. + + The annotation mechanism has largely been superseded by GDB/MI. + + "--args" + Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior. This option + stops option processing. - -b bps + "-baud bps" + "-b bps" Set the line speed (baud rate or bits per second) of any serial interface used by GDB for remote debugging. - -tty=device + "-l timeout" + Set the timeout (in seconds) of any communication used by GDB for remote debugging. + + "-tty device" + "-t device" Run using device for your program's standard input and output. + "-tui" + Activate the Text User Interface when starting. The Text User Interface manages several text windows on the terminal, showing source, assembly, registers + and GDB command outputs. Do not use this option if you run GDB from Emacs. + + "-interpreter interp" + Use the interpreter interp for interface with the controlling program or device. This option is meant to be set by programs which communicate with GDB + using it as a back end. + + --interpreter=mi (or --interpreter=mi2) causes GDB to use the GDB/MI INTERFACE included since GDB version 6.0. The previous GDB/MI interface, included in + GDB version 5.3 and selected with --interpreter=mi1, is deprecated. Earlier GDB/MI interfaces are no longer supported. + + "-write" + Open the executable and core files for both reading and writing. This is equivalent to the set write on command inside GDB. + + "-statistics" + This option causes GDB to print statistics about time and memory usage after it completes each command and returns to the prompt. + + "-version" + This option causes GDB to print its version number and no-warranty blurb, and exit. + + "-configuration" + This option causes GDB to print details about its build-time configuration parameters, and then exit. These details can be important when reporting GDB + bugs. + SEE ALSO The full documentation for GDB is maintained as a Texinfo manual. If the "info" and "gdb" programs and GDB's Texinfo documentation are properly installed at your site, the command