From: Nicholas Nethercote Date: Mon, 10 Aug 2009 01:15:30 +0000 (+0000) Subject: Be consistent in the naming of sections describing command-line options. X-Git-Tag: svn/VALGRIND_3_5_0~92 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0ea383e6b3865dbfef63a1485707c1b0351ec3f2;p=thirdparty%2Fvalgrind.git Be consistent in the naming of sections describing command-line options. Also, use "option" rather than "flag" where possible, for consistency. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10758 --- diff --git a/docs/xml/FAQ.xml b/docs/xml/FAQ.xml index 8454f2e237..9ee8ea3d08 100644 --- a/docs/xml/FAQ.xml +++ b/docs/xml/FAQ.xml @@ -132,7 +132,7 @@ collect2: ld returned 1 exit status older glibc versions causes this crash. Workaround for 1.1.X and later versions of Valgrind: use the - flag. You may then get space + option. You may then get space leak reports for glibc allocations (please don't report these to the glibc people, since they are not real leaks), but at least the program runs. @@ -424,7 +424,7 @@ Invalid write of size 1 If you are tracing large trees of processes, it can be less disruptive to have the output sent over the network. Give Valgrind - the flag (if you want + the option (if you want logging output sent to port 12345 on localhost). You can use the valgrind-listener program to listen on that port: @@ -557,7 +557,7 @@ int main(void) Prior to version 3.4.0, the answer was "we don't know how to do it without huge performance penalties". As of 3.4.0, try using the - flag. It will run slower than + option. It will run slower than usual, but will give you extra information about the origin of uninitialised values. diff --git a/docs/xml/manual-core-adv.xml b/docs/xml/manual-core-adv.xml index bf02d073ac..d04a962c16 100644 --- a/docs/xml/manual-core-adv.xml +++ b/docs/xml/manual-core-adv.xml @@ -511,7 +511,7 @@ will honour only the first one. Figuring out what's going on given the dynamic nature of wrapping can be difficult. The - flag makes + option makes this possible by showing the complete state of the redirection subsystem after every @@ -550,7 +550,7 @@ of both sets following any such event. time an active specification is used for the first time. Hence for maximum debugging effectiveness you will need to use both -flags. +options. One final comment. The function-wrapping facility is closely tied to Valgrind's ability to replace (redirect) specified diff --git a/docs/xml/manual-core.xml b/docs/xml/manual-core.xml index 9104078840..a3fa73c64d 100644 --- a/docs/xml/manual-core.xml +++ b/docs/xml/manual-core.xml @@ -7,10 +7,10 @@ Using and understanding the Valgrind core -This chapter describes the Valgrind core services, flags and -behaviours. That means it is relevant regardless of what particular -tool you are using. The information should be sufficient for you to -make effective day-to-day use of Valgrind. Advanced topics related to +This chapter describes the Valgrind core services, command-line +options and behaviours. That means it is relevant regardless of what +particular tool you are using. The information should be sufficient for you +to make effective day-to-day use of Valgrind. Advanced topics related to the Valgrind core are described in . @@ -41,7 +41,7 @@ Memcheck, issue this command: valgrind --tool=memcheck ls -l]]> However, Memcheck is the default, so if you want to use it you can -omit the flag. +omit the option. Regardless of which tool is in use, Valgrind takes control of your program before it starts. Debugging information is read from the @@ -94,17 +94,17 @@ tool(s) each suppression applies to. First off, consider whether it might be beneficial to recompile your application and supporting libraries with debugging info enabled -(the flag). Without debugging info, the best +(the option). Without debugging info, the best Valgrind tools will be able to do is guess which function a particular piece of code belongs to, which makes both error messages and profiling output nearly useless. With , you'll get messages which point directly to the relevant source code lines. -Another flag you might like to consider, if you are working with +Another option you might like to consider, if you are working with C++, is . That makes it easier to see the function-call chain, which can help reduce confusion when navigating around large C++ apps. For example, debugging -OpenOffice.org with Memcheck is a bit easier when using this flag. You +OpenOffice.org with Memcheck is a bit easier when using this option. You don't have to do this, but doing so helps Valgrind produce more accurate and less confusing error reports. Chances are you're set up like this already, if you intended to debug your program with GNU GDB, or some @@ -145,7 +145,7 @@ Valgrind will result in you getting error reports pertaining to /bin/sh, /usr/bin/perl, or whatever interpreter you're using. This may not be what you want and can be confusing. You -can force the issue by giving the flag +can force the issue by giving the option , but confusion is still likely. @@ -171,7 +171,7 @@ processes which have become merged together, for whatever reason. By default, Valgrind tools write only essential messages to the commentary, so as to avoid flooding you with information of secondary importance. If you want more information about what is happening, -re-run, passing the flag to Valgrind. A second +re-run, passing the option to Valgrind. A second gives yet more detail. @@ -235,7 +235,7 @@ re-run, passing the flag to Valgrind. A second connections in round brackets. valgrind-listener accepts two - command-line flags: + command-line options: or : @@ -335,8 +335,8 @@ defined in m_errormgr.c and can be increased if necessary. To avoid this cutoff you can use the - flag. Then Valgrind will always show -errors, regardless of how many there are. Use this flag carefully, + option. Then Valgrind will always show +errors, regardless of how many there are. Use this option carefully, since it may have a bad effect on performance. @@ -361,8 +361,8 @@ don't want to fix, yet you don't want to continuously be reminded of them. Note: By far the easiest way to add -suppressions is to use the flag -described in . This generates +suppressions is to use the option +described in . This generates suppressions automatically. For best results, though, you may want to edit the output of by hand, in which @@ -376,7 +376,7 @@ suppresses a bunch of similar errors which you did want to see. The suppression mechanism is designed to allow precise yet flexible specification of errors to suppress. -If you use the flag, at the end of execution, +If you use the option, at the end of execution, Valgrind prints out one line for each used suppression, giving its name and the number of times it got used. Here's the suppressions used by a run of valgrind --tool=memcheck ls -l: @@ -550,19 +550,19 @@ to malloc.. - -Command-line flags for the Valgrind core + +Core Command-line Options -As mentioned above, Valgrind's core accepts a common set of flags. -The tools also accept tool-specific flags, which are documented +As mentioned above, Valgrind's core accepts a common set of options. +The tools also accept tool-specific options, which are documented separately for each tool. Valgrind's default settings succeed in giving reasonable behaviour in most cases. We group the available options by rough categories. - -Tool-selection option + +Tool-selection Option The single most important option. @@ -637,7 +637,7 @@ in most cases. We group the available options by rough categories. of your program, such as: the shared objects loaded, the suppressions used, the progress of the instrumentation and execution engines, and warnings about unusual behaviour. Repeating - the flag increases the verbosity level. + the option increases the verbosity level. @@ -671,7 +671,7 @@ in most cases. We group the available options by rough categories. a fork call. This can make the output less confusing (although more misleading) when dealing with processes that create children. It is particularly useful in conjunction - with --trace-children=. Use of this flag is also + with --trace-children=. Use of this option is also strongly recommended if you are requesting XML output (--xml=yes), since otherwise the XML from child and parent may become mixed up, which usually makes it useless. @@ -780,7 +780,7 @@ in most cases. We group the available options by rough categories. -Error-related options +Error-related Options These options are used by all tools @@ -815,7 +815,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. docs/internals/xml-output-protocol4.txt in the source tree for Valgrind 3.5.0 or later. - The recommended flags for a GUI to pass, when requesting + The recommended options for a GUI to pass, when requesting XML output, are: to enable XML output, to send the XML output to a (presumably GUI-selected) file, to send the plain @@ -1079,7 +1079,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. debugged. Since <command> is likely - to contain spaces, you will need to put this entire flag in + to contain spaces, you will need to put this entire option in quotes to ensure it is correctly handled by the shell. @@ -1104,7 +1104,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. - This flag is only relevant when running Valgrind on + This option is only relevant when running Valgrind on Mac OS X. Mac OS X uses a deferred debug information (debuginfo) @@ -1184,7 +1184,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. option allows you to change the threshold to a different value. - You should only consider use of this flag if Valgrind's + You should only consider use of this option if Valgrind's debug output directs you to do so. In that case it will tell you the new threshold you should specify. @@ -1194,7 +1194,7 @@ that can report errors, e.g. Memcheck, but not Cachegrind. support large numbers of threads each with a small stack, and also because the error checking performed by Memcheck is more effective for heap-allocated data than for stack-allocated data. If you - have to use this flag, you may wish to consider rewriting your + have to use this option, you may wish to consider rewriting your code to allocate on the heap rather than on the stack. @@ -1337,7 +1337,7 @@ need to use these. and ppc64/Linux, Valgrind always provides complete, transparent support for self-modifying code. It is only on platforms such as x86/Linux, AMD64/Linux and x86/Darwin that you need to use this - flag. + option. @@ -1385,7 +1385,7 @@ need to use these. - This flag is only relevant when running Valgrind on Linux. + This option is only relevant when running Valgrind on Linux. The GNU C library (libc.so), which is used by all programs, may allocate memory for its own uses. @@ -1405,7 +1405,7 @@ need to use these. Unfortunately, in some very old versions of glibc, __libc_freeres is sufficiently buggy to cause segmentation faults. This was particularly noticeable on Red Hat - 7.1. So this flag is provided in order to inhibit the run of + 7.1. So this option is provided in order to inhibit the run of __libc_freeres. If your program seems to run fine on Valgrind, but segfaults at exit, you may find that fixes that, although at the @@ -1480,8 +1480,8 @@ need to use these. - -Debugging Valgrind Options + +Debugging Options There are also some options for debugging @@ -1493,8 +1493,8 @@ things. If you wish to see the list, use the - -Setting default Options + +Setting Default Options Note that Valgrind also reads options from three places: @@ -1639,7 +1639,7 @@ with make regtest. This builds Valgrind with some special magic hacks which make it possible to run it on a standard build of Valgrind (what the developers call "self-hosting"). Ordinarily you should not use - this flag as various kinds of safety checks are disabled. + this option as various kinds of safety checks are disabled. @@ -1659,7 +1659,7 @@ with make regtest. platforms (amd64-linux, ppc64-linux), Valgrind is by default built in such a way that both 32-bit and 64-bit executables can be run. Sometimes this cleverness is a problem for a variety of reasons. - These two flags allow for single-target builds in this situation. + These two options allow for single-target builds in this situation. If you issue both, the configure script will complain. Note they are ignored on 32-bit-only platforms (x86-linux, ppc32-linux). @@ -1784,7 +1784,7 @@ subject to the following constraints: code has changed, and work correctly. This is necessary to handle the trampolines GCC uses to implemented nested functions. If you regenerate code somewhere other than the stack, you will need to use - the flag, and Valgrind will run more + the option, and Valgrind will run more slowly than normal. Or you can add client requests that tell Valgrind when your program has overwritten code. diff --git a/docs/xml/manual-intro.xml b/docs/xml/manual-intro.xml index 1d1e42ab4a..452effd360 100644 --- a/docs/xml/manual-intro.xml +++ b/docs/xml/manual-intro.xml @@ -112,7 +112,7 @@ distribution. How to navigate this manual This manual's structure reflects the structure of Valgrind itself. -First, we describe the Valgrind core, how to use it, and the flags +First, we describe the Valgrind core, how to use it, and the options it supports. Then, each tool has its own chapter in this manual. You only need to read the documentation for the core and for the tool(s) you actually use, although you may find it helpful to be at least a little @@ -120,10 +120,10 @@ bit familiar with what all tools do. If you're new to all this, you probably want to run the Memcheck tool and you might find the useful. -Be aware that the core understands some command line flags, and -the tools have their own flags which they know about. This means -there is no central place describing all the flags that are -accepted -- you have to read the flags documentation both for +Be aware that the core understands some command line options, and +the tools have their own options which they know about. This means +there is no central place describing all the options that are +accepted -- you have to read the options documentation both for and for the tool you want to use.