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 <[email protected]>是Valgrind的初始作者，在
/usr/share/doc/valgrind/AUTHORS還有其他的貢獻者的信息。
這份手冊由Andres Roldan <[email protected]>爲Debian工程編寫，但是可以在
任何其它發行版上使用。

2.4.0版本的更新，重排，和擴展由Robert Walsh <[email protected]>,
後來由其它的Valgrind開發者完成。

本手冊的翻譯工作由鄧傑和莊禮深同學共同完成。