Valgrind User Manual

Name:
Valgrind is a debugging and profiling Program Tool set.

Summary usage:
Valgrind [[valgrind] [Options] [Your-program] [[Your-Program-options]

Overview:
Valgrind is a flexible debugging and profiling executable tool in Linux. It is integrated by the software layer
CPU kernel, and a series of debugging and profiling tools. The architecture is modular, so you can
On the basis of some structures, it is easy to create new tools.
This manual includes basic usage and options. For more information, see the html
Documentation:
/Usr/share/doc/valgrind/html/index.html
Or online document:
Http://www.valgrind.org/docs/manual/index.html.

Usage:
Valgrind is called as follows:
Valgrind program ARGs

In this way, the memcheck program Program (with The args parameter) will be run in valgrind ). Memory check
Execute a series of memory check functions, including detecting access to uninitialized memory and memory allocation errors
Use (two releases, release before access, etc.) and check for Memory leakage.

Available -- tool specifies other tools:
Valgrind -- tool = toolname program ARGs

The following tools are available:
O cachegrind is a buffer simulator. It can be used to mark the commands executed by each line of your program
And the number of cache hits.

O callgrind adds call tracing Based on cachegrind. It can be used to obtain the number of calls
And the overhead of each function call. As a supplement to cachegrind, callgrind can
Mark the execution times of each thread and each instruction output by program disassembly and cache miss
Number.

O helgrind can discover potential conditional competition in programs.

O lackey is a sample program that can be used as a template to create your own tools. After the program ends,
It prints some basic program execution statistics.

O massif is a heap analyzer that measures how much heap memory your program uses.

O memcheck is a fine-grained memory checker.

O none does not have any function. It is generally used for valgrind debugging and benchmarking.

Basic options:
These options are valid for all tools.

-H -- Help
Displays help for all options, including the kernel and the selected tool.

-- Help-Debug
It is the same as -- help, and can also display debugging that is usually only used by valgrind developers.
.

-- Version
The version number of the valgrind kernel is displayed. The tool can have its own version number. This is
A setting that ensures that the tool only works on the kernel that they can run. This can reduce the number
The probability that version compatibility between tools and kernels causes strange issues.

-Q -- quiet
Run quietly and only print the error message. Perform regression tests or perform other automated tests.
The trial mechanism is very useful.

-V -- verbose
Displays details. Displays additional information about your program in various aspects, such as shared objects.
Attach, reset, execute the process of the engine and tool, and warn of abnormal behaviors. Heavy
Repeat this tag to increase the detailed level.

-D debug information sent by valgrind itself. Usually only valgrind developers are interested in this.
Repeat this tag to produce more detailed output. If you want to send a bug report
Output generated by-V-D will make your report more effective.

-- Tool = <toolname> [Default: memcheck]
Run valgrind specified by toolname, such as memcheck, addrcheck, cachegrind,
And so on.

-- Trace-Children = <Yes | NO> [Default: No]
When this option is enabled, valgrind will track the sub-process. This often leads to confusion, and
This option is disabled by default because it is not what you expect.

-- Track-FDS = <Yes | NO> [Default: No]
When this option is enabled, valgrind prints a list of opened file descriptors upon exit.
Each file descriptor prints the stack rollback where a file is opened, and any
Detailed information related to file descriptors, such as file names or socket information.

-- Time-stamp = <Yes | NO> [Default: No]
When this option is enabled, each piece of information has a time before it expires from the beginning of the program, in days,
Hours, minutes, seconds, and milliseconds.

-- Log-FD = <number> [Default: 2, stderr]
Specify valgrind to output all its messages to a specified file descriptor. Default Value
2. It is a standard error output (stderr ). Note that this may interfere with the client's own stderr
The valgrind output and the client program output will be interspersed to stderr.

-- Log-file = <FILENAME>
Specify valgrind to output all its information to the specified file. In fact,
The file name is connected by filename, '.', and process number (that is, <FILENAME>. <pid> ),
Thus, each process creates different files.

-- Log-file-exactly = <FILENAME>
Similar to -- log-file, but the suffix ". PID" is not added. If this option is set,
Using valgrind to track multiple processes may lead to a mess of files.

-- Log-file-qualifier = <var>
When used with -- log-file, the log file name is filtered by the environment variable $ var. This
It is beneficial for MPI programs. For more details, see Section 2.3 "Annotations" in the manual ".

-- Log-socket = <IP-Address: Port-number>
Specify valgrind to output all messages to the specified IP address and the specified port. When port 1500 is used
The port may be ignored. If you cannot establish a connection to the specified port, valgrind
Write the output to a standard error (stderr ). This option is often used with a valgrind listener.
Start to use. For more details, see Section 2.3 "Annotations" in the manual ".

Error related options:
These options apply to all tools that generate errors, such as memcheck, but not cachegrind.

-- Xml = <Yes | NO> [Default: No]
When this option is enabled, the output will be in XML format. This is to use valgrind output
Input tools, such as GUI front-end, are easier. Currently, this option only takes effect during memcheck.

-- XML-user-Comment = <string>
Append user comments at the beginning of XML and take effect only when -- xml = yes is specified; otherwise, ignore.

-- Demangle = <Yes | NO> [Default: Yes]
Enable/disable automatic Decoding of C ++ names. Enabled by default. When it is enabled, valgrind will try
The encoded C ++ name is automatically converted back to the initial state. This decoder can process version 2.xof g ++,
3. X or 4. x.

An important fact about name encoding and decoding is that decoding function names in files are prohibited from being used.
They are not decoded. Valgrind does not decode function names when searching for available prohibited entries,
This will disable the file content from relying on the name decoding mechanism of valgrind, which will speed
Slow and meaningless.

-- Num-callers = <number> [Default: 12]
By default, valgrind displays the name of the function called by the layer-12 function to help determine the position of the program.
You can use this option to change the number. This will help determine the hierarchy of nested calls when they are very deep.
The location of the program. Note that the error message is usually traced back to the top four functions. (Current function, and
The location of the three callers ). Therefore, this does not affect the total number of errors reported.

The maximum value of this value is 50. High-attention setting slows down valgrind and uses more
But it is very useful in programs with a higher hierarchy of nested calls.

-- Error-Limit = <Yes | NO> [Default: Yes]
When this option is enabled, the total number reaches 10,000,000, or 1,000 different errors,
Valgrind stops reporting errors. This is to avoid many errors in the Error Tracking Mechanism.
It becomes a huge performance burden.

-- error-exitcode = [Default: 0]
specifies the exit return value if valgrind reports any errors during running, there are two conditions
; when set to the default value (0), valgrind returns the value of the program it simulates to run
the returned value. If it is set to a non-zero value, valgrind returns this value if it finds any error.
This is useful when valgrind is used as part of a test tool suite, because the
tool test kit only checks the valgrind return value to know which test cases valgrind reports an error.
.

-- Show-below-Main = <Yes | NO> [Default: No]
By default, stack backtracking in case of errors does not display any function (or similar function image) under main ().
Glibc _ libc_start_main (), if main () does not appear in stack rollback );
Some are boring C-library functions. If this option is enabled, the function under main () is also
Will be displayed.

-- Suppressions = <FILENAME> [Default: $ prefix/lib/valgrind/Default. Supp]
Specify an extra file read error that does not need to be ignored; you can use any number
.

-- Gen-suppressions = <Yes | no | all> [Default: No]
When set to yes, valgrind will automatically pause and print after each error is displayed.
This line:
---- Print suppression? --- [Return/n/y/C] ----

The behavior of this prompt is the same as that of the -- DB-Attach option (see below.

If you select Yes, valgrind will print an incorrect deny entry. You can cut it and
Paste it to a file. If you do not want to see this error message in the future.

When it is set to all, valgrind prints a deny entry for each error, instead
Ask.

This option is very useful to C ++ programs and prints the name adjusted by the compiler.

Note that the printed prohibited entries are as specific as possible. To generalize similar entries
For example, add a wildcard to the function name. In addition, sometimes two different errors
If the same prohibited entries are generated, valgrind will output more than once.
Only one copy is required for the object to be banned (but if there are more than one copy, it will not cause any questions.
Question ). In addition, the name of the prohibited entry is as follows: <enter a name for the prohibited entry here>
It is not very important. It is used with the-V option to print all prohibited entry records used.

-- DB-Attach = <Yes | NO> [Default: No]
When this option is enabled, valgrind will pause every printing error and output the following
One row:

---- Attach to debugger? --- [Return/n/y/C] ----

Press enter, or N, press enter, N, and press Enter. valgrind does not start the debugger for this error.

Press Y, press enter, or Y, and valgrind will start the debugger and set it
This point. When the debugging is completed, the program continues to run. Try to continue in the debugger
The running program will not take effect.

Press C, press enter, or C, and press Enter. valgrind will not start a debugger and will not start
.

Note: -- DB-Attach = Yes conflicts with -- Trace-Children = yes. You cannot use
They. Valgrind cannot be started in this case.

2002.05: this is a historical heritage. If this problem affects you, please send an email and
Complain about this problem.

2002.11: If you send logs to the log file or to the network port, I guess this won't make you have
Any feeling. Ignore.

-- DB-command = <command> [Default: GDB-NW % F % P]
Use -- DB-attach to specify how to use the debugger. The default debugger is GDB. the default option
Is a runtime extension valgrind template. % F will be replaced with the executable file name,
% P will be replaced by the process ID of the executable file.

This specifies how valgrind will call the debugger. The default option is not checked during construction.
It is changed by testing GDB, usually/usr/bin/GDB. You can specify some
Call other debuggers to replace them.

The command string can contain one or more % P % F extensions. Every % P instance is
It is interpreted as the PID of the debugging process. Each % F instance is interpreted as
Path of the execution file.

-- Input-FD = <number> [Default: 0, stdin]
Use the -- DB-Attach = yes and -- gen-suppressions = Yes options. When an error is found,
Valgrind stops reading the keyboard input. By default, it is disabled because it is read from the standard input.
There will be problems with the standard input program. This option allows you to specify a file descriptor to replace
Read standard input.

-- Max-stackframe = <number> [Default: 2000000]
The maximum value of the stack. Valgrind considers the program
Switched to another stack for execution.

If the program has a large number of stack-allocated arrays, you may need to use this option.
Valgrind keeps track of the program Stack pointer. If the treasure pointer offset exceeds this number,
Valgrind assumes that your program has switched to another stack, and memcheck behavior and stack
The offset of the needle does not exceed this quantity. This mechanism usually works well. However,
If your program applies for a large structure on the stack, this mechanism will be stupid and
Memcheck will report a large amount of illegal stack memory access. This option allows you to set this threshold.
Is another value.

This option should be used only when this is required in the debugging output of valgrind. Here
In this case, it will tell you the new threshold value that should be specified.

Generally, allocating large volumes of memory in the stack is a bad idea. Because it's easy to use up your
Stack space, especially in systems with limited memory or systems that support a large number of threads with small stacks,
Because memcheck performs an error check, it is more efficient to compare the data on the stack to the data on the stack.
A lot. If you use this option, you may want to rewrite it.CodeAllocate memory on the heap
Instead of allocating resources on the stack.

Malloc () related options:
For using your own version of malloc () (such as memcheck and Massif), the following options can be used.
-- Alignment = <number> [Default: 8]
The default malloc () and realloc () of valgrind are 8-byte alignment addresses. This
Is the standard for most processors. However, some programs may assume that malloc () and so on always return
16 bytes or more alignment memory. The provided value must be within the range of 8 and 4096, and
It must be a power of 2.

Non-General options:
These options can be used for all tools that affect several features of valgrind core. Most people do not
These options are used.

-- Run-libc-freeres = <Yes | NO> [Default: Yes]
The gnu c library (libc. So), which is shared by all programs, may allocate a part of memory for self-use. Connect
It is not troublesome to release the memory when the program exits. It is okay because the Linux Kernel
When a process exits, it recycles all the resources of the process. Therefore, this only causes a slow speed.

The author of glibc realized that this would lead to a memory checker, such as valgrind, checking upon exit
Memory error reports glibc memory leakage issues, in order to avoid this problem, they provide
A _ libc_freeres () routine is used to release all allocated memory for glibc.
Therefore, memcheck tries to run _ libc_freeres () when exiting ().

unfortunately, in some glibc versions, __libc_freeres has bugs that may cause segment errors.
This is a special statement on Red Hat 7.1. Therefore, this option is provided to determine whether to run
_ libc_freeres. If your program seems to run well on valgrind but a segment error occurs when
exit, you may need to specify -- run-libc-freeres = No to fix it, this will report possible errors to libc. so memory leakage.

-- sim-hints = hint1, hint2 ,...
pass the Hang prompts to valgrind to slightly modify the non-standard or dangerous mode of simulated behavior.
it may be helpful to simulate strange features. No prompt is displayed by default. Use it with caution! Currently,
prompts are as follows:
O Lax-IOCTLs: the processing of IOCTL is not strict, and the only assumption is that the size is correct.
the buffer zone does not need to be fully initialized during writing. Without this, using a large number of strange IOCTL
commands to use some device drivers will be very annoying.
O enable-inner: enable some special effects when the running program is valgrind itself.

-- Kernel-variant = variant1, variant2 ,...
Processing System calls and IOCTLs generate different variables on the default core of the platform. This helps
Run on the improved kernel or non-standard IOCTLs. Use it with caution. If you do not
To understand what this option is, you almost don't need it. Known variables include:
O bproc: supports sys_broc system calls on the X86 platform. This is to run in bproc,
It is a variant of standard Linux and is sometimes used to build clusters.

-- Show-emwarns = <Yes | NO> [Default: No]
When this option is enabled, valgrind will generate a warning for CPU simulation in some specific situations.
These are usually not noticeable.

-- SMC-check = <none | stack | all> [Default: Stack]
This option controls valgrind's detection of Self-modified code. Valgrind does not check,
It can detect self-modified code in the stack or any part of the stack. Note:
The default option is to capture the vast majority of cases, so far as we know. Use the all option
It greatly reduces the speed. (However, running with the none option rarely affects the speed, because
Program, a very small amount of code is added to the stack)

Debug valgrind options:
Some other options are used to debug valgrind itself. This is not required when running common things.
If you want to see the Option List, use the -- Help-debug option.

memory check options:
-- leak-check = [Default: Summary]
when this option is enabled, when the client program ends, it finds the memory leakage. Memory leakage means that
memory blocks are allocated with malloc, but no free release is used, and no pointer is directed to this block
memory. Such memory blocks cannot be released by the program because no Pointer Points to them. For example, if the value is set to summary, valgrind reports the memory leakage. If it is set to
full or yes, valgrind provides detailed information about each independent leak.

-- show-reachable = [Default: No]
when this option is disabled, the Memory Leak Detector displays only memory blocks without pointers, or
only the pointer pointing to the middle of the block can be found. When this option is enabled, the memory leak detector also reports memory blocks pointed to by pointers. These blocks are the most likely locations for memory leaks. Your
program may, at least in principle, release these memory blocks before exiting. These memory blocks that point to the
needle and memory blocks that do not point to the pointer, or that only point to the internal pointer,
may cause memory leakage, because no pointer pointing to the starting block can be used to release
, even if you want to release it.

-- leak-resolution = [Default: Low]
when performing a memory leak check, determine how memcheck will consider the situation where different stacks are the same.
when set to low, only the first two layers of stack matching are considered the same; when set to Med,
layer-4 stack matching is required, when it is set to high, all layers of stacks must match.
for the hardcore memory leak check, you may need to use -- leak-resolution = high and
-- num-callers = 40 or a larger number. Note that this will generate a huge amount of information, which is why
the default options are four callers matching and low-resolution matching.
Note: -- leak-resolution = setting does not affect the memcheck Memory leakage. It
only changes how the result is output.

-- Freelist-Vol = <number> [Default: 5000000]
When the customer program uses free (in C) or delete (c ++) to release the memory, the memory is not
It can be immediately used for redistribution. These memories will be marked as inaccessible and put into one
In the queue with released memory. The purpose of this operation is to reuse the released memory.
Try to be as late as possible. This helps memcheck check the block during the important time after the memory block is released.
Invalid access.

This option specifies the total memory capacity that the queue can accommodate, in bytes. The default value is
5000000 bytes. Increasing this number will increase the memory used by memcheck, but it also increases
Probability of unauthorized use of released memory.

-- workaround-gcc296-bugs = [Default: No]
when this option is enabled, it is assumed that the short distance below the read/write Stack pointer is a GCC 2.96 bug,
and no error is reported. The distance is 256 bytes by default. Note that GCC 2.96 is the default compiler for some older
Linux distributions (RedHat 7.x), so you may need to use this option.
if it is not necessary, do not use this option. It may cause some real errors.
A better solution is to use a newer version, which fixes the GCC/g ++ version of this bug. -- Partial-loads-OK = [Default: No]
controls the word length and word alignment when memcheck reads data from an address, therefore, which bytes are addressable and which are not addressable
. When set to yes, such a read will not throw an addressing error
. The vword segments read from invalid addresses are displayed as undefined, and access to the valid addresses is still mapped to the memory as usual.

When it is set to no, reading from some wrong addresses is the same as reading from a completely wrong address:
An Invalid Address error is thrown, and the vword section of the result is displayed as valid data.

Note that this code behavior violates the iso c/C ++ standard and should be considered problematic. If yes
Yes. This code should be corrected. This option should be used as a final consideration.

-- UNDEF-value-errors = <Yes | NO> [Default: Yes]
Controls whether memcheck checks for the dangerous use of undefined values. Memcheck row when set to Yes
A lightweight memory check tool, like addrcheck, is a part of valgrind
Does not check for undefined value errors. Use this option if you do not want to see an undefined value error.

Cachegrind options:
Manually specify the i1/D1/L2 buffer configuration, in bytes. The three must be separated by commas (,).
There is no space, for example:
Valgrind -- tool = cachegrind -- I1 = 65535,2, 64

You can specify one, two, or three I1/D1/L2 buffers. If not manually specified, use
The configuration obtained by using the common method (obtain the buffer configuration through the cpuid command, and use the default value if it fails.

-- I1 = <size>, <associativity>, <line size>
Specify the buffer size, correlation level, and row size of the first-level command.

-- D1 = <size>, <associativity>, <line size>
Specifies the size, correlation, and row size of the first-level data buffer.

-- L2 = <size>, <associativity>, <line size>
Specify the second-level buffer size, correlation level, and row size.

Callgrind options:
-- Heap = <Yes | NO> [Default: Yes]
When this option is enabled, the usage of the heap is tracked in detail. When this option is disabled,
Massif.pid.txtor massif.pid.html will be very short.

-- Heap-Admin = <number> [Default: 8]
The number of management bytes used by each block. This can only use an average estimate because it may change.
The alignment used by glibc requires 4 ~ 15 bytes, depending on various factors. Manage released
Blocks also need space, although massif does not calculate these.

-- Stacks = <Yes | NO> [Default: Yes]
When opened, stack information is included in the profiling information. A multi-threaded program may have multiple stacks.

-- Depth = <number> [Default: 3]
The depth of the calling process in the detailed heap information. Adding this value gives more information,
Massif will make the program run slowly, use more memory, and generate a large
The massif.pid.txt or massif. PID. HP file.

-- Alloc-fn = <Name>
Specifies a function for allocating memory. This is useful for packaging functions that use malloc ().
It is used to fill in the original invalid context information. (These functions provide useless context information,
And give the meaningless area in the figure ). The specified function is ignored in the context. For example
Same as malloc. This option can be repeated multiple times in the command line to specify multiple functions.

-- Format = <text | HTML> [Default: text]
Detailed information of the text HTML format. The file extension uses .txt0000.html.

Helgrind options:
-- Private-stacks = <Yes | NO> [Default: No]
It is assumed that the thread stack is private.

-- Show-last-access = <Yes | some | NO> [Default: No]
Displays the location of the last word access error.

Lackey options:
-- Fnname = <Name> [Default: _ dl_runtime_resolve ()]
Count the <Name> function.

-- Detailed-counts = <no | Yes> [Default: No]
Reads, stores, and Alu operations.

Refer:
/Usr/share/doc/valgrind/html/index.html, and/or
Http://www.valgrind.org/docs/manual/index.html.author information:
Julian Seward <jseward@acm.org> is the initial author of valgrind
/Usr/share/doc/valgrind/authors and other contributors.
This manual was written by Andres Roldan <aroldan@debian.org> for the Debian project, but you can
Used on any other release.

2.4.0 version updates, rearrangements, and extensions by Robert Walsh <rjwalsh@durables.org>,
Later, it was completed by other valgrind developers.