學習筆記之 curl 命令用法詳解

【前言】 
    本文翻譯和整理自 Linux-2.6.32 中和 curl 相關的 Manual Page 描述文檔。 文檔目的僅在提醒讀者所遺忘的知識點，故在整理時削弱了閱讀流暢性，適用於對 curl 有一定了解的開發人員。 

【語法】 
    curl [options] [URL...] 

【概述】 
    curl 命令用作網絡數據包收發，常應用於非交互式環境中。 
    URL 的格式依賴於命令所使用的網絡協議，相關詳細信息可以查看《RFC 3986》文檔。 

    如果在一條命令中訪問多個文件，crul 會嘗試在多個傳輸會話間重用一個連接，以此減少建立不必要的連接或握手，從而訪問速度。 
    多個相互獨立的 curl 命令調用之間不支持連接重用。 

    curl 運行時，默認啟用傳輸進度條用於顯示總傳輸數據大小、傳輸速度、預計剩余傳輸時間等。 
    進度條數據默認直接輸出到控制台。如果不希望這些數據在你 POST 或 PUT 時擾亂了 response數據包，可以使用重定向 > 或后跟參數 -o [file] 或其它同樣功能的語句將相應數據重定向到文件中。 
    使用參數 -# 可以讓她看起來更像真正的進度“條”。 

【URL技巧】 
    字符串匹配    http://site. {one,two,three}.com 
    字符匹配    ftp://ftp.letters.com/file [a-z].txt 
    數字匹配    ftp://ftp.numerical.com/file [1-100].txt 
    混合匹配    http://any.org/archive[1996-1999]/vol[1-4]/part{a,b,c}.html 
    步進匹配    http://www.numerical.com/file [1-100:10].txt 
                     http://www.letters.com/file [a-z:2].txt 

【option參數】 
    -h/--help    顯示 curl 命令使用方法的簡要幫助信息 
    -M/--manual    顯示詳細幫助文檔 
    -a/--append    向服務器端文件追加內容。如果服務器端文件不存在，將創建該文件。 
    -A/--user-agent <agent string>    為 HTTP 數據包指定 User-Agent 字段內容，即瀏覽器信息。如果內容含有空格，請使用單引號括起來。有的網站要求訪問者必須使用特定的瀏覽器甚至版本，這種情況下可以使用該參數繞過服務器的檢測。 
    -H/--header <header string>    為 HTTP 數據包指定 Header 字段內容。如果要刪除某個 header 字段，可以使用 <字段名>: 的格式替換 <header string> 代表的內容。比如刪除 Host 字段的內容，可以這樣添加 -H 參數：-H "Host:" 
                                                     不要手動為你的 header 內容添加換行標記 \r\n，因為 curl 會幫你處理，否則只會讓你的代碼出現莫名奇妙的問題。 
                                                     添加、替換、刪除 header 字段的操作均由該參數實現。 
    -I/--head    只接收 response數據包中 header 字段的內容。 
    -b/--cookie <name=data>    為發送的 HTTP 數據包指定 cookie 內容，通常是之前同服務器通訊時，從服務器接收到的 response數據包中 Set-Cookie 字段中的內容。如果要指定多對值，格式為“NAME1=VALUE1;NAME2=VALUE2”。 
                                                 如果內容中沒有等號 =，則會被解析為存儲 Cookie 的文件，此時還應該配合參數 -L/--location 使用。 
    -c/--cookie-jar <filename>    存儲 response數據包中的 cookie 信息到文件中。如果文件名是破折號 -，則 cookie 將在 stdout 被打印出來。Cookie信息使用 Netscape cookie文件的格式進行記錄。cookie 寫入失敗不會導致 curl 命令中止，使用 -v 參數可以在操作失敗時看到警告信息。 
    -D/--dump-header <filename>    存儲 response數據包中的 header 信息到文件中。在 FTP 傳輸中使用時，FTP 服務器的回復消息會被視作 headers 存儲起來。 
    --connect-timeout <seconds>    設置連接超時。這個值是對於連接建立階段而言的，一旦連接被建立，這個限制就沒用了。 
    -m/--max-time
    -C/--continue-at <offset>    斷點續傳。<offset>是一個數值，表示從文件頭開始計算的要跳過的字節數。如果<offset>被設定為破折號 -，那么 curl 命令將自行檢測待傳輸文件的斷點位置。 
    --create-dirs    創建目錄。通常與參數 -o 連用，用於為 /dir/filename 這樣的參數創建目錄 dir/。比如 -c /recvDir/cookie.txt --create-dirs 
    --ftp-create-dirs    為 FTP/SFTP 傳輸創建遠程目錄。 
    --crlf    在 FTP 上傳中將 LF 轉換為 CRLF。 
    -d/--data <data>    為 POST 數據包指定要向 HTTP 服務器發送的數據並發送出去。這個過程和在瀏覽器中點擊“submit”按鈕是一樣的，且數據將以 content-type application/x-www-form-urlencoded 的方式被編碼。 
                                    在同一條命令中多次使用 -d 參數，參數后的內容會被符號 & 拼接起來。比如 -d name=daniel -d skill=lousy 會被轉化為 name=daniel&skill=lousy 
                                   如果<data>的內容以符號 @ 開頭，其后的字符串將被解析為文件名，curl 命令會從這個文件中讀取數據發送，但文件中的內容必須是 URL 編碼的格式；如果內容以符號 - 開頭，curl 命令將從 stdin 讀取數據發送。 
    --data-binary <data>    為 POST 數據包指定要向 HTTP 服務器發送的數據並發送出去。數據將以二進制的形式被送出。 
    --data-urlencode <data>    為 POST 數據包指定要向 HTTP 服務器發送的數據並發送出去。數據在發送前將進行 URL-encode 編碼。 
    --digest    為 HTTP 傳輸啟用摘要加密算法，防止登錄信息被明文傳輸。通常在其后使用 -u/--user 參數指定用戶名和密碼。 
    --ntlm
    --negotiate
    --anyauth
    -e/--referer <URL>    為 HTTP 數據包指定 Referer Page 信息，即前一個被訪問頁面的 URL。通常這個信息被服務器用於判斷自己是否被盜鏈，如果發現服務器端有這樣的檢測機制，則可以使用該參數繞過檢測。 
    -E/--cert <certificate[:password]>    為 HTTPS/FTPS 數據包指定數字證書。數字證書必須是 PEM 格式。如果 password 沒有在內容中顯式給定，則會在連接建立時被服務器端詢問。 
    -f/--fail    禁止服務器在打開頁面失敗或腳本調用失敗時向客戶端發送錯誤說明，取而代之，curl 會返回錯誤碼 22。 
    -F/--form <name=content>    模擬用戶在瀏覽器上點擊“submit”按鈕提交表單的操作。如果想提交文件，可以將<name=content>中 content部分的內容替換為 @filename 的格式；如果想提交文件中的內容，可以將 content部分的內容替換為 <filename 格式；如果想提交從 stdin 獲取的到的數據，可以將 content部分的內容替換為 @- 或者 <- 
                                                   比如，要提交存儲密碼的文件到服務器上，命令為：curl -F password=@/etc/passwd www.mypasswords.com 
                                                   要將文件中的內容作為密碼提交到服務器上，命令為：curl -F password=</etc/passwd www.mypasswords.com 
                                                   在<name=content>內容中添加“type=xxx”字段可以指定 Content-Type 類型。 
                                                   比如 curl -F "web=@index.html;type=text/html" url.com  
                                                   或者 curl -F "name=daniel;type=text/foo" url.com 
                                                   還可以從文件讀取待發送內容后，修改數據包中的文件名信息，像這樣：curl -F "file=@localfile;filename=nameispost" url.com 
    -g/--globoff    關閉 URL 的通配符功能。這樣就可以訪問名稱中含有字符 {、}、[、] 的文件了。 
    -G/--get    將 -d 參數后指定的數據以 GET 方法打包發送，並在數據末尾添加一個問號 ? 
    --hostpubmd5 <md5>    為數據包指定一個 32 位的十六進制數。這個數應該與遠程服務器公鑰的 MD5 值相同。如果 MD5 值不相同，curl 將中止連接。這個參數只在 SCP/SFTP 傳輸協議中使用。 
    -i/--include    使輸出信息中包含 HTTP-header 的內容，比如 server-name、HTTP-version 等。 
    --interface <name>    使用指定網卡訪問/傳輸數據。命令格式：curl --interface eth0:1 http://www.netscape.com/ 
    --keepalive-time <seconeds>    為連接設定保活時間。這個值同時也是相鄰 2 次發送保活消息的時間間隔。 
    --K/--config <config file>   為 curl 命令指定一個配置文件，curl 會從該文件中讀取內容並作為自己的運行參數。 默認的配置文件是 ~/.curlrc。當 <config file> 的內容被寫成符號 - 時，curl 會從 stdin 讀取配置。 
                                                配置文件每一行只能寫一個參數；支持使用符號 \ 對字符進行轉義；如果內容中含有空格，需用引號括起來；以符號 # 開始的內容會被視為注釋；文件中的 URL 信息需要寫成 url = URL 這樣的格式。 
                                                配置文件示例如下：
                                                # --- Example file ---
                                                # this is a comment
                                                url = "curl.haxx.se"
                                                output = "curlhere.html"
                                                user-agent = "superagent/1.0"
                                                # and fetch another URL too
                                                url = "curl.haxx.se/docs/manpage.html"
                                                -O
                                                referer = "http://nowhereatall.com/"
                                                # --- End of example file --- 
    -q    如果這個參數是 curl 命令的第一個參數，那么 curl 命令將不會去讀取默認的 curlrc 配置文件。 
    --libcurl <file>    將本條命令實現的功能轉換成調用 libcurl 的 C 代碼，並保存在 <file> 文件中。但是目前還不能很好地轉化帶 -F 參數的命令。 
    --limit-rate <speed>    為數據包指定最大傳輸速率，這樣就不會占用整個帶寬。通常在數據處理管道不夠用時使用。默認的速率單位是 bytes/s，如果在數字后加上 k、m、g 等后綴，如 200k，則表示 200Kb/s。 
    --local-port <num>[-num]    為連接指定一個本地端口。 
    --L/--location   當服務器報告被請求的頁面已被移動到另一個位置時（通常返回 3XX 錯誤代碼）， 允許 curl 使用新的地址重新訪問。如果跳轉鏈接指向了一個不同的主機，curl 將不向其發送用戶名和密碼。 
    --location-trusted    該參數和 -L 參數類似，也可讓 curl 繼續訪問跳轉鏈接，區別在於該參數允許向跳轉鏈接發送明文用戶名和密碼。 
    --max-redirs <num>   指定最大跳轉次數。默認的次數限制為 50。如果將 <num> 設置為 -1 表示不進行限制。 
    -m/--max-time <seconds>    為數據傳輸過程指定超時時間。如果傳輸過程在這個時間內沒有完成，連接將被中止。防止腳本因為網絡不好或鏈接失效而掛死。 
    -o/--output <file>    將獲取到的數據存入文件中，而不是打印出來。如果在 URL 中使用了 {} 或 [] 進行通配，我們就可以在 <file> 中使用 #1、#2 ... 的形式來順序表示這些通配符中的內容。 
                                     比如下面這樣的寫法： 
                                     curl http://{one,two}.site.com -o "file_#1.txt" 
                                     curl http://{site,host}.host[1-5].com -o "#1_#2" 
    -O/--remote-name    在本地保存獲取的數據時，使用她們在遠程服務器上的文件名進行保存。 
    --random-file <file>    為 SSL 連接指定一個存有隨機數的種子的文件。 
    --retry <num>    在數據包的傳輸失敗時，為其指定重試次數。默認次數為 0，即不重傳。連接超時、500錯誤代碼都會引起重傳。 
    -s/--silent   將 curl 設定在靜默模式下工作。進度條和錯誤消息都不會被顯示。 
    --stderr <file>    重定向錯誤輸出到文件。 
    -T/--upload-file <file>   這個參數用於向遠程服務器傳輸指定文件。上傳文件時，URL必須以符號 / 結尾才會被識別為目錄。當文件名是符號 - 時，curl 將從 stdin 讀取輸入數據進行上傳。如果遠端是 HTTP 服務器，那么應該使用 PUT 方法。 
                                          命令格式如下： 
                                          curl -T "{file1,file2}" http://www.uploadtothissite.com 
                                          curl -T "img[1-1000].png" ftp://ftp.picturemania.com/upload/ 
    --trace <file>    啟用對所有數據包傳輸的追蹤，並記錄到指定文件中。當文件名是符號 - 時，追蹤消息將輸出到標准輸出。 
    --trace-ascii <file>    類似於 --trace ，但是是以 ascii 的形式輸出的而非十六進制，便於閱讀。
    -u/--user <user:password>    為數據傳輸在服務器端的身份驗證提供用戶名/密碼信息。
    -U/--proxy-user <username:password>    為數據傳輸在代理服務器上的身份驗證提供用戶名/密碼信息。 
    -v/--verbose    顯示數據傳輸過程中的詳細信息。 
    -V/--version    顯示 curl 及其所使用的 libcurl 的版本信息。 
    -w/--write-out <format>    在數據傳輸完成后，輸出和本次傳輸相關的參數信息，比如 header 的大小、下載速度等。<format>部分即格式化輸出內容，變量使用格式為 %{varible}，使用 %% 輸出百分號 %，使用 \r、\n、\t 輸出 回車、換行、制表符。 
                                               所有支持的變量如下表所示： 
                                               url_effective    上次訪問的URL。 
                                               http_code    上一次 HTTP 或 FTP 數據傳輸過程中的 response 數值代碼。 
                                               http_connect    上一次 CONNECT 請求中的數值代碼 
                                               time_total    數據傳輸消耗的總時間，以秒為單位，精度為毫秒。 
                                               time_namelookup    從數據傳輸開始到域名解析完成所花費的時間。 
                                               time_connect    TCP連接建立成功所花費的時間。 
                                               time_appconnect    應用層協議，如 SSL/SSH、三次握手等過程完成所花費的時間。 
                                               time_redirect    從跳轉鏈接被激活到真正開始從跳轉鏈接下載數據所經過的時間。 
                                               time_starttransfer    從請求連接開始，到第一個字節被傳送前所經過的時間。 
                                               size_download    數據傳輸過程中下載的總數據大小。
                                               size_upload    數據傳輸過程中上傳的總數據大小。
                                               size_header    下載的數據包中，header 字段的總數據大小。
                                               size_request    被發送的 HTTP request 的總數據大小。
                                               speed_download    整個數據傳輸過程中的平均數據下載速度。 
                                               speed_upload    整個數據傳輸過程中的平均數據上傳速度。 
                                               content_type    被請求訪問的文件的 Content_Type 類型。 
                                               num_redirects    訪問請求中包含的跳轉鏈接數量。 
                                               redirect_url    跳轉鏈接指向的URL 
                                               ssl_verify_result    SSL驗證的結果。值為 0 時表示驗證成功。 
    -x/--proxy <proxyhost[:port]>    為數據傳輸指定代理服務器。如果沒有顯示指定端口號，則使用默認端口號1080 
    -X/--request <command>    為 HTTP 數據包指定一個方法，比如 PUT、DELETE。默認的方法是 GET。 
    -z/--time-cond <date expression>    請求一個時間點比 <date expression> 中描述的時間更早或更晚的文件。<date expression>以符號 - 開始時表示訪問比該時間點更早的文件，以數字開始時表示訪問比該時間點更晚的文件。 
    -0/--http1.0    強制在 HTTP 傳輸時使用 HTTP 1.0 協議。默認使用 HTTP 1.1 
    -1/--tlsv1    強制在 SSL 傳輸時使用 TLS v1 協議 
    -2/--sslv2    強制在 SSL 傳輸時使用 SSL v2 協議 
    -3/--sslv3    強制在 SSL 傳輸時使用 SSL v3 協議 
    -4/--ipv4    強制解析域名為 IPv4 地址 
    -6/--ipv6    強制解析域名為 IPv6 地址 

【退出代碼/返回值】 
    1    curl 不支持該協議 
    2    curl 初始化失敗 
    3    URL 格式錯誤 
    5    解析代理服務器失敗 
    6    解析主機失敗 
    7    建立與主機的連接失敗 
    8    無法解析 FTP 服務器返回的消息 
    9    FTP 服務器拒接訪問。可能是拒絕登錄或拒絕訪問特定目錄，但很多情況下是訪問了一個不存在的位置導致的 
    11    無法解析 FTP 服務器的 PASS 回復消息 
    13    無法解析 FTP 服務器的 PASV 回復消息 
    14    無法解析 FTP 服務器的 227-line 回復消息 
    15    無法解析 FTP 主機 
    17    無法與 FTP 服務器建立二進制傳輸模式 
    18    文件傳輸不完整。只有文件的一部分被傳送了。 
    19    FTP 下載/訪問指定的文件失敗 
    21    FTP 引用錯誤 
    22    HTTP 頁面獲取失敗。將返回 400 及其以上的錯誤碼。 
    23    寫入數據到本地文件系統發生錯誤 
    25    FTP 服務器無法存儲被上傳的文件 
    26    讀取數據出錯 
    27    內存分配失敗 
    28    操作超時 
    30    FTP 服務器運行 PORT 命令失敗 
    31    FTP 服務器運行 REST 命令失敗 
    33    HTTP 服務器執行 range 命令失敗 
    34    HTTP 服務器 post 方法錯誤 
    35    SSL 連接出錯。通常是 SSL 握手失敗。 
    36    FTP 斷點續傳出錯，無法繼續前一次下載任務。 
    37    FILE 協議無法打開文件。可能是沒有權限導致的 
    38    LDAP 協議無法執行 bind 操作 
    39    LDAP 協議執行搜索功能失敗 
    41    沒有找到匹配的 LDAP 功能 
    42    curl 被其它應用程序中止運行 
    43    發生內部錯誤。通常是因為調用函數時傳遞了錯誤的參數 
    45    接口調用錯誤 
    47    跳轉鏈接數量達到上限 
    48    為 telnet 協議指定了一個未知的參數 
    49    telnet 協議的參數格式有誤 
    51    SSL 認證或 SSH 的 MD5 指紋不正確 
    52    服務器無應答 
    53    未找到 SSL 加密引擎 
    54    無法將 SSL 加密引擎設為默認引擎 
    55    發送網絡數據失敗 
    56    接收網絡數據失敗 
    58    本地證書有問題 
    59    無法使用指定的 SSL 密碼 
    60    已知的 CA證書無法用於驗證 
    61    無法識別傳輸編碼 
    62    無效的 LDAP URL 
    63    文件大小超過限制 
    64    請求的 FTP SSL 級別獲取失敗 
    65    發送需要進行 rewind 的數據失敗 
    66    解析 SSL 引擎失敗 
    67    用戶名/密碼驗證失敗，curl 無法登錄 
    68    TFTP 服務器上沒有找到指定的文件 
    69    對 TFTP 服務器的訪問出現權限問題 
    70    TFTP 服務器已耗盡磁盤空間 
    71    非法的 TFTP 操作 
    72    未知的 TFTP 傳輸 ID 
    73    TFTP 企圖傳輸一個已經存在的文件 
    74    用戶不存在導致 TFTP 操作失敗 
    75    字符轉換失敗 
    76    需要使用字符轉換函數 
    77    讀取 SSL CA 證書出錯。可能是證書路徑不正確，也可能是沒有權限 
    78    URL 中指定的資源不存在 
    79    SSH 會話中發生了未知錯誤 
    80    中斷 SSH 連接失敗 
    82    無法加載 CRL 文件。可能是沒有指定正確的格式 
    83    發布者身份驗證失敗