valgrind中文命令行帮助

名字：
       valgrind是一个调试和剖析的程序工具集。

概要用法：
       valgrind [[valgrind] [options]] [your-program] [[your-program-options]]

概述：
       Valgrind是一个Linux下灵活的调试和剖析可执行工具。它由在软件层提供综合的
       CPU内核,和一系列调试、剖析的工具组成。架构是模块化的，所以可以在不破坏现
       有的结构的基础上很容易的创建出新的工具来。
       这本手册包括了基本的用法和选项。更多帮助理解的信息，请查看您系统的HTML
       文档：
       　　/usr/share/doc/valgrind/html/index.html
       或者在线文档：
       　　http://www.valgrind.org/docs/manual/index.html.

用法：
       一般像下面这样调用Valgrind:
           valgrind program args

       这样将在Valgrind使用Memcheck运行程序program(带有参数args)。内存检查
       执行一系列的内存检查功能，包括检测访问未初始化的内存，已经分配内存的错误
       使用(两次释放，释放后再访问，等等)并检查内存泄漏。

       可用--tool指定使用其它工具：
           valgrind --tool=toolname program args

       可使用的工具如下：
       o cachegrind是一个缓冲模拟器。它可以用来标出你的程序每一行执行的指令
          数和导致的缓冲不命中数。

       o callgrind在cachegrind基础上添加调用追踪。它可以用来得到调用的次数
          以及每次函数调用的开销。作为对cachegrind的补充，callgrind可以分别
          标注各个线程，以及程序反汇编输出的每条指令的执行次数以及缓存未命中
          数。

       o helgrind能够发现程序中潜在的条件竞争。

       o lackey是一个示例程序，以其为模版可以创建你自己的工具。在程序结束后，
       它打印出一些基本的关于程序执行统计数据。

       o massif是一个堆剖析器，它测量你的程序使用了多少堆内存。

       o memcheck是一个细粒度的的内存检查器。

       o none没有任何功能。它它一般用于Valgrind的调试和基准测试。

基本选项：
       这些选项对所有工具都有效。

       -h --help
              显示所有选项的帮助，包括内核和选定的工具两者。

       --help-debug
              和--help相同，并且还能显示通常只有Valgrind的开发人员使用的调试
              选项。

       --version
              显示Valgrind内核的版本号。工具可以有他们自已的版本号。这是一种
              保证工具只在它们可以运行的内核上工作的一种设置。这样可以减少在
              工具和内核之间版本兼容性导致奇怪问题的概率。

       -q --quiet
              安静的运行，只打印错误信息。在进行回归测试或者有其它的自动化测
              试机制时会非常有用。

       -v --verbose
              显示详细信息。在各个方面显示你的程序的额外信息，例如：共享对象
              加载，使用的重置，执行引擎和工具的进程，异常行为的警告信息。重
              复这个标记可以增加详细的级别。

       -d     调试Valgrind自身发出的信息。通常只有Valgrind开发人员对此感兴趣。
              重复这个标记可以产生更详细的输出。如果你希望发送一个bug报告，通
              过-v -v -d -d生成的输出会使你的报告更加有效。

       --tool=<toolname> [default: memcheck]
              运行toolname指定的Valgrind，例如，Memcheck, Addrcheck, Cachegrind,
              等等。

       --trace-children=<yes|no> [default: no]
              当这个选项打开时，Valgrind会跟踪到子进程中。这经常会导致困惑，而
              且通常不是你所期望的，所以默认这个选项是关闭的。

       --track-fds=<yes|no> [default: no]
              当这个选项打开时，Valgrind会在退出时打印一个打开文件描述符的列表。
              每个文件描述符都会打印出一个文件是在哪里打开的栈回溯，和任何与此
              文件描述符相关的详细信息比如文件名或socket信息。


       --time-stamp=<yes|no> [default: no]
              当这个选项打开时，每条信息之前都有一个从程序开始消逝的时间，用天，
              小时，分钟，秒和毫秒表示。

       --log-fd=<number> [default: 2, stderr]
              指定Valgrind把它所有的消息都输出到一个指定的文件描述符中去。默认值
              2,　是标准错误输出(stderr)。注意这可能会干扰到客户端自身对stderr
              的使用, Valgrind的输出与客户程序的输出将穿插在一起输出到stderr。

       --log-file=<filename>
              指定Valgrind把它所有的信息输出到指定的文件中。实际上，被创建文件的
              文件名是由filename、'.'和进程号连接起来的（即<filename>.<pid>），
              从而每个进程创建不同的文件。

       --log-file-exactly=<filename>
              类似于--log-file，但是后缀".pid"不会被添加。如果设置了这个选项，
              使用Valgrind跟踪多个进程，可能会得到一个乱七八糟的文件。            

       --log-file-qualifier=<VAR>
              当和--log-file一起使用时，日志文件名将通过环境变量$VAR来筛选。这
              对于MPI程序是有益的。更多的细节，查看手册2.3节 "注解"。

       --log-socket=<ip-address:port-number>
              指定Valgrind输出所有的消息到指定的IP，指定的端口。当使用1500端口
              时，端口有可能被忽略。如果不能建立一个到指定端口的连接，Valgrind
              将输出写到标准错误(stderr)。这个选项经常和一个Valgrind监听程序一
              起使用。更多的细节，查看手册2.3节 "注解"。


错误相关选项：
       这些选项适用于所有产生错误的工具，比如Memcheck,　但是Cachegrind不行。

       --xml=<yes|no> [default: no]
              当这个选项打开时，输出将是XML格式。这是为了使用Valgrind的输出做为
              输入的工具，例如GUI前端更加容易些。目前这个选项只在Memcheck时生效。

       --xml-user-comment=<string>
              在XML开头 附加用户注释，仅在指定了--xml=yes时生效，否则忽略。

       --demangle=<yes|no> [default: yes]
              打开/关闭C++的名字自动解码。默认打开。当打开时，Valgrind将尝试着把
              编码过的C++名字自动转回初始状态。这个解码器可以处理g++版本为2.X,
              3.X或4.X生成的符号。

              一个关于名字编码解码重要的事实是，禁止文件中的解码函数名仍然使用
              他们未解码的形式。Valgrind在搜寻可用的禁止条目时不对函数名解码，
              因为这将使禁止文件内容依赖于Valgrind的名字解码机制状态， 会使速度
              变慢，且无意义。

       --num-callers=<number> [default: 12]
              默认情况下，Valgrind显示12层函数调用的函数名有助于确定程序的位置。
              可以通过这个选项来改变这个数字。这样有助在嵌套调用的层次很深时确定
              程序的位置。注意错误信息通常只回溯到最顶上的4个函数。(当前函数，和
              它的3个调用者的位置)。所以这并不影响报告的错误总数。

              这个值的最大值是50。注意高的设置会使Valgrind运行得慢，并且使用更多
              的内存,但是在嵌套调用层次比较高的程序中非常实用。

       --error-limit=<yes|no> [default: yes]
              当这个选项打开时，在总量达到10,000,000，或者1,000个不同的错误，
              Valgrind停止报告错误。这是为了避免错误跟踪机制在错误很多的程序
              下变成一个巨大的性能负担。

       --error-exitcode=<number> [default: 0]
              指定如果Valgrind在运行过程中报告任何错误时的退出返回值，有两种情
              况；当设置为默认值(零)时，Valgrind返回的值将是它模拟运行的程序的
              返回值。当设置为非零值时，如果Valgrind发现任何错误时则返回这个值。
              在Valgrind做为一个测试工具套件的部分使用时这将非常有用，因为使测
              试工具套件只检查Valgrind返回值就可以知道哪些测试用例Valgrind报告
              了错误。

       --show-below-main=<yes|no> [default: no]
              默认地，错误时的栈回溯不显示main()之下的任何函数(或者类似的函数像
              glibc的__libc_start_main()，如果main()没有出现在栈回溯中)；这些大
              部分都是令人厌倦的C库函数。如果打开这个选项，在main()之下的函数也
              将会显示。

       --suppressions=<filename> [default: $PREFIX/lib/valgrind/default.supp]
              指定一个额外的文件读取不需要理会的错误；你可以根据需要使用任意多
              的额外文件。

       --gen-suppressions=<yes|no|all> [default: no]
              当设置为yes时，Valgrind将会在每个错误显示之后自动暂停并且打印下
              面这一行：
                  ---- Print suppression ? --- [Return/N/n/Y/y/C/c] ----


              这个提示的行为和--db-attach选项(见下面)相同。

              如果选择是，Valgrind会打印出一个错误的禁止条目，你可以把它剪切然后
              粘帖到一个文件，如果不希望在将来再看到这个错误信息。

              当设置为all时，Valgrind会对每一个错误打印一条禁止条目，而不向用户
              询问。

              这个选项对C++程序非常有用，它打印出编译器调整过的名字。

              注意打印出来的禁止条目是尽可能的特定的。如果需要把类似的条目归纳
              起来，比如在函数名中添加通配符。并且，有些时候两个不同的错误也会
              产生同样的禁止条目，这时Valgrind就会输出禁止条目不止一次，但是在
              禁止条目的文件中只需要一份拷贝(但是如果多于一份也不会引起什么问
              题)。并且，禁止条目的名字像<在这儿输入一个禁止条目的名字>;名字并
              不是很重要，它只是和-v选项一起使用打印出所有使用的禁止条目记录。

       --db-attach=<yes|no> [default: no]
              当这个选项打开时，Valgrind将会在每次打印错误时暂停并打出如下
              一行：

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

              按下回车,或者N、回车，n、回车，Valgrind不会对这个错误启动调试器。

              按下Y、回车，或者y、回车，Valgrind会启动调试器并设定在程序运行的
              这个点。当调试结束时，退出，程序会继续运行。在调试器内部尝试继续
              运行程序，将不会生效。

              按下C、回车，或者c、回车，Valgrind不会启动一个调试器，并且不会再
              次询问。

              注意：--db-attach=yes与--trace-children=yes有冲突。你不能同时使用
              它们。Valgrind在这种情况下不能启动。

              2002.05: 这是一个历史的遗留物，如果这个问题影响到你，请发送邮件并
              投诉这个问题。

              2002.11:如果你发送输出到日志文件或者到网络端口，我猜这不会让你有
              任何感觉。不须理会。

       --db-command=<command> [default: gdb -nw %f %p]
              通过--db-attach指定如何使用调试器。默认的调试器是gdb.默认的选项
              是一个运行时扩展Valgrind的模板。 %f会用可执行文件的文件名替换，
              %p会被可执行文件的进程ID替换。

              这指定了Valgrind将怎样调用调试器。默认选项不会因为在构造时是否检
              测到了GDB而改变,通常是/usr/bin/gdb.使用这个命令，你可以指定一些
              调用其它的调试器来替换。

              给出的这个命令字串可以包括一个或多个%p %f扩展。每一个%p实例都被
              解释成将调试的进程的PID，每一个%f实例都被解释成要调试的进程的可
              执行文件路径。            

       --input-fd=<number> [default: 0, stdin]
              使用--db-attach=yes和--gen-suppressions=yes选项，在发现错误时，
              Valgrind会停下来去读取键盘输入。默认地，从标准输入读取，所以关闭
              了标准输入的程序会有问题。这个选项允许你指定一个文件描述符来替代
              标准输入读取。

       --max-stackframe=<number> [default: 2000000]
              栈的最大值。如果栈指针的偏移超过这个数量，Valgrind则会认为程序是
              切换到了另外一个栈执行。

              如果在程序中有大量的栈分配的数组，你可能需要使用这个选项。
              valgrind保持对程序栈指针的追踪。如果栈指针的偏移超过了这个数量，
              Valgrind假定你的程序切换到了另外一个栈，并且Memcheck行为与栈指
              针的偏移没有超出这个数量将会不同。通常这种机制运转得很好。然而，
              如果你的程序在栈上申请了大的结构，这种机制将会表现得愚蠢，并且
              Memcheck将会报告大量的非法栈内存访问。这个选项允许把这个阀值设置
              为其它值。

              应该只在Valgrind的调试输出中显示需要这么做时才使用这个选项。在这
              种情况下，它会告诉你应该指定的新的阀值。

              普遍地，在栈中分配大块的内存是一个坏的主意。因为这很容易用光你的
              栈空间，尤其是在内存受限的系统或者支持大量小堆栈的线程的系统上，
              因为Memcheck执行的错误检查，对于堆上的数据比对栈上的数据要高效
              很多。如果你使用这个选项，你可能希望考虑重写代码在堆上分配内存
              而不是在栈上分配。
MALLOC()相关的选项:
       对于使用自有版本的malloc() (例如Memcheck和massif)，下面的选项可以使用。

       --alignment=<number> [default: 8]
              默认Valgrind的malloc(),realloc(), 等等，是8字节对齐地址的。这
              是大部分处理器的标准。然而，一些程序可能假定malloc()等总是返回
              16字节或更多对齐的内存。提供的数值必须在8和4096区间之内，并且
              必须是2的幂数。

非通用选项：
       这些选项可以用于所有的工具，它们影响Valgrind core的几个特性。大部分人不
       会用到这些选项。

       --run-libc-freeres=<yes|no> [default: yes]
　　　　　　　GNU C库(libc.so)，所有程序共用的，可能会分配一部分内存自已用。通
              常在程序退出时释放内存并不麻烦 -- 这里没什么问题，因为Linux内核在
              一个进程退出时会回收进程全部的资源，所以这只是会造成速度慢。
            
              glibc的作者认识到这样会导致内存检查器，像Valgrind，在退出时检查
              内存错误的报告glibc的内存泄漏问题，为了避免这个问题，他们提供了
              一个__libc_freeres()例程特别用来让glibc释放分配的所有内存。
              因此Memcheck在退出时尝试着去运行__libc_freeres()。

              不幸的是，在glibc的一些版本中，__libc_freeres是有bug会导致段错误的。
              这在Red Hat 7.1上有特别声明。所以，提供这个选项来决定是否运行
              __libc_freeres。如果你的程序看起来在Valgrind上运行得很好，但是在
              退出时发生段错误，你可能需要指定--run-libc-freeres=no来修正，这将
              可能错误的报告libc.so的内存泄漏。

       --sim-hints=hint1,hint2,...
              传递杂凑的提示给Valgrind，轻微的修改模拟行为的非标准或危险方式，
              可能有助于模拟奇怪的特性。默认没有提示打开。小心使用！目前已知
              的提示有：
              o lax-ioctls: 对ioctl的处理非常不严格，唯一的假定是大小是正确的。
              不需要在写时缓冲区完全的初始化。没有这个，用大量的奇怪的ioctl
              命令来使用一些设备驱动将会非常烦人。
              o enable-inner:打开某些特殊的效果，当运行的程序是Valgrind自身时。

       --kernel-variant=variant1,variant2,...
              处理系统调用和ioctls在这个平台的默认核心上产生不同的变量。这有助
              于运行在改进过的内核或者支持非标准的ioctls上。小心使用。如果你不
              理解这个选项做的是什么那你几乎不需要它。已经知道的变量有：
              o bproc: 支持X86平台上的sys_broc系统调用。这是为了运行在BProc，
              它是标准Linux的一个变种，有时用来构建集群。

       --show-emwarns=<yes|no> [default: no]
              当这个选项打开时，Valgrind在一些特定的情况下将对CPU仿真产生警告。
              通常这些都是不引人注意的。

       --smc-check=<none|stack|all> [default: stack]
              这个选项控制Valgrind对自我修改的代码的检测。Valgrind可以不做检测，
              可以检测栈中自我修改的代码，或者任意地方检测自我修改的代码。注意
              默认选项是捕捉绝大多数情况，到目前我们了解的情况为止。使用all选项
              时会极大的降低速度。(但是用none选项运行极少影响速度，因为对大多数
              程序，非常少的代码被添加到栈中)


调试VALGRIND选项：
       还有一些选项是用来调试Valgrind自身的。在运行一般的东西时不应该需要的。
       如果你希望看到选项列表，使用--help-debug选项。

内存检查选项：
       --leak-check=<no|summary|yes|full> [default: summary]
              当这个选项打开时，当客户程序结束时查找内存泄漏。内存泄漏意味着
              有用malloc分配内存块，但是没有用free释放，而且没有指针指向这块
              内存。这样的内存块永远不能被程序释放，因为没有指针指向它们。如
              果设置为summary，Valgrind会报告有多少内存泄漏发生了。如果设置为
              full或yes，Valgrind给出每一个独立的泄漏的详细信息。

       --show-reachable=<yes|no> [default: no]
              当这个选项关闭时，内存泄漏检测器只显示没有指针指向的内存块，或
              者只能找到指向块中间的指针。当这个选项打开时，内存泄漏检测器还
              报告有指针指向的内存块。这些块是最有可能出现内存泄漏的地方。你
              的程序可能，至少在原则上，应该在退出前释放这些内存块。这些有指
              针指向的内存块和没有指针指向的内存块，或者只有内部指针指向的块，
              都可能产生内存泄漏，因为实际上没有一个指向块起始的指针可以拿来释
              放，即使你想去释放它。

       --leak-resolution=<low|med|high> [default: low]
              在做内存泄漏检查时，确定memcheck将怎么样考虑不同的栈是相同的情况。
              当设置为low时，只需要前两层栈匹配就认为是相同的情况；当设置为med，
              必须要四层栈匹配，当设置为high时，所有层次的栈都必须匹配。
            
              对于hardcore内存泄漏检查，你很可能需要使用--leak-resolution=high和
              --num-callers=40或者更大的数字。注意这将产生巨量的信息，这就是为什
              么默认选项是四个调用者匹配和低分辨率的匹配。
              注意--leak-resolution= 设置并不影响memcheck查找内存泄漏的能力。它
              只是改变了结果如何输出。

       --freelist-vol=<number> [default: 5000000]
              当客户程序使用free(C中)或者delete(C++)释放内存时，这些内存并不是
              马上就可以用来再分配的。这些内存将被标记为不可访问的，并被放到一
              个已释放内存的队列中。这样做的目的是，使释放的内存再次被利用的点
              尽可能的晚。这有利于memcheck在内存块释放后这段重要的时间检查对块
              不合法的访问。

              这个选项指定了队列所能容纳的内存总容量，以字节为单位。默认的值是
              5000000字节。增大这个数目会增加memcheck使用的内存，但同时也增加了
              对已释放内存的非法使用的检测概率。

       --workaround-gcc296-bugs=<yes|no> [default: no]
              当这个选项打开时，假定读写栈指针以下的一小段距离是gcc 2.96的bug，
              并且不报告为错误。距离默认为256字节。注意gcc 2.96是一些比较老的
              Linux发行版(RedHat 7.X)的默认编译器，所以你可能需要使用这个选项。
              如果不是必要请不要使用这个选项，它可能会使一些真正的错误溜掉。
              一个更好的解决办法是使用较新的，修正了这个bug的gcc/g++版本。

       --partial-loads-ok=<yes|no> [default: no]
              控制memcheck如何处理从地址读取时字长度，字对齐，因此哪些字节是可
              以寻址的，哪些是不可以寻址的。当设置为yes是，这样的读取并不抛出
              一个寻址错误。而是从非法地址读取的V字节显示为未定义，访问
              合法地址仍然是像平常一样映射到内存。

              设置为no时，从部分错误的地址读取与从完全错误的地址读取同样处理：
              抛出一个非法地址错误，结果的V字节显示为合法数据。

              注意这种代码行为是违背ISO C/C++标准，应该被认为是有问题的。如果可
              能，这种代码应该修正。这个选项应该只是做为一个最后考虑的方法。

       --undef-value-errors=<yes|no> [default: yes]
              控制memcheck是否检查未定义值的危险使用。当设为yes时，Memcheck的行
              为像Addrcheck, 一个轻量级的内存检查工具，是Valgrind的一个部分，它
              并不检查未定义值的错误。使用这个选项，如果你不希望看到未定义值错误。


CACHEGRIND选项：
       手动指定I1/D1/L2缓冲配置，大小是用字节表示的。这三个必须用逗号隔开，中间
       没有空格，例如：
           valgrind --tool=cachegrind --I1=65535,2,64

       你可以指定一个，两个或三个I1/D1/L2缓冲。如果没有手动指定，每个级别使用
       普通方式(通过CPUID指令得到缓冲配置，如果失败，使用默认值)得到的配置。

       --I1=<size>,<associativity>,<line size>
              指定第一级指令缓冲的大小，关联度和行大小。

       --D1=<size>,<associativity>,<line size>
              指定第一级数据缓冲的大小，关联度和行大小。

       --L2=<size>,<associativity>,<line size>
              指定第二级缓冲的大小，关联度和行大小。

CALLGRIND选项：
       --heap=<yes|no> [default: yes]
              当这个选项打开时，详细的追踪堆的使用情况。关闭这个选项时，
              massif.pid.txt或massif.pid.html将会非常的简短。

       --heap-admin=<number> [default: 8]
              每个块使用的管理字节数。这只能使用一个平均的估计值，因为它可能变化。
              glibc使用的分配器每块需要4~15字节，依赖于各方面的因素。管理已经释放
              的块也需要空间，尽管massif不计算这些。            

       --stacks=<yes|no> [default: yes]
              当打开时，在剖析信息中包含栈信息。多线程的程序可能有多个栈。

       --depth=<number> [default: 3]
              详细的堆信息中调用过程的深度。增加这个值可以给出更多的信息，但是
              massif会更使这个程序运行得慢，使用更多的内存，并且产生一个大的
              massif.pid.txt或者massif.pid.hp文件。

       --alloc-fn=<name>
              指定一个分配内存的函数。这对于使用malloc()的包装函数是有用的，可以
              用它来填充原来无效的上下文信息。(这些函数会给出无用的上下文信息，
              并在图中给出无意义的区域)。指定的函数在上下文中被忽略，例如，像对
              malloc()一样处理。这个选项可以在命令行中重复多次，指定多个函数。

       --format=<text|html> [default: text]
              产生text或者HTML格式的详细堆信息，文件的后缀名使用.txt或者.html。

HELGRIND选项：
       --private-stacks=<yes|no> [default: no]
              假定线程栈是私有的。

       --show-last-access=<yes|some|no> [default: no]
              显示最后一次字访问出错的位置。

LACKEY选项：
       --fnname=<name> [default: _dl_runtime_resolve()]
              对<name>函数计数。

       --detailed-counts=<no|yes> [default: no]
              对读取，存储和alu操作计数。

参考：
        /usr/share/doc/valgrind/html/index.html, 和/或者
       http://www.valgrind.org/docs/manual/index.html.

作者信息：
       Julian Seward <[e-mail]>是Valgrind的初始作者，在
       /usr/share/doc/valgrind/AUTHORS还有其他的贡献者的信息。
       这份手册由Andres Roldan <[e-mail]>为Debian工程编写，但是可以在
       任何其它发行版上使用。
     
       2.4.0版本的更新，重排，和扩展由Robert Walsh <[e-mail]>,
       后来由其它的Valgrind开发者完成。

       本手册的翻译工作由邓杰和庄礼深同学共同完成。