package exec · Go 標準庫中文參考

# package exec `import "os/exec"` exec包執行外部命令。它包裝了os.StartProcess函數以便更容易的修正輸入和輸出，使用管道連接I/O，以及作其它的一些調整。 ## Index * [Variables](#pkg-variables) * [type Error](#Error) * [func (e \*Error) Error() string](#Error.Error) * [type ExitError](#ExitError) * [func (e \*ExitError) Error() string](#ExitError.Error) * [func LookPath(file string) (string, error)](#LookPath) * [type Cmd](#Cmd) * [func Command(name string, arg ...string) \*Cmd](#Command) * [func (c \*Cmd) StdinPipe() (io.WriteCloser, error)](#Cmd.StdinPipe) * [func (c \*Cmd) StdoutPipe() (io.ReadCloser, error)](#Cmd.StdoutPipe) * [func (c \*Cmd) StderrPipe() (io.ReadCloser, error)](#Cmd.StderrPipe) * [func (c \*Cmd) Run() error](#Cmd.Run) * [func (c \*Cmd) Start() error](#Cmd.Start) * [func (c \*Cmd) Wait() error](#Cmd.Wait) * [func (c \*Cmd) Output() ([]byte, error)](#Cmd.Output) * [func (c \*Cmd) CombinedOutput() ([]byte, error)](#Cmd.CombinedOutput) ### Examples * [Cmd.Output](#example-Cmd-Output) * [Cmd.Start](#example-Cmd-Start) * [Cmd.StdoutPipe](#example-Cmd-StdoutPipe) * [Command](#example-Command) * [LookPath](#example-LookPath) ## Variables ``` var ErrNotFound = errors.New("executable file not found in $PATH") ``` 如果路徑搜索沒有找到可執行文件時，就會返回本錯誤。 ## type [Error](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L25 "View Source") ``` type Error struct { Name string Err error } ``` Error類型記錄執行失敗的程序名和失敗的原因。 ### func (\*Error) [Error](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L30 "View Source") ``` func (e *Error) Error() string ``` ## type [ExitError](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L329 "View Source") ``` type ExitError struct { *os.ProcessState } ``` ExitError報告某個命令的一次未成功的返回。 ### func (\*ExitError) [Error](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L333 "View Source") ``` func (e *ExitError) Error() string ``` ## func [LookPath](https://github.com/golang/go/blob/master/src/os/exec/lp_unix.go#L33 "View Source") ``` func LookPath(file string) (string, error) ``` 在環境變量PATH指定的目錄中搜索可執行文件，如file中有斜杠，則只在當前目錄搜索。返回完整路徑或者相對于當前目錄的一個相對路徑。 Example ``` path, err := exec.LookPath("fortune") if err != nil { log.Fatal("installing fortune is in your future") } fmt.Printf("fortune is available at %s\n", path) ``` ## type [Cmd](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L35 "View Source") ``` type Cmd struct { // Path是將要執行的命令的路徑。 // // 該字段不能為空，如為相對路徑會相對于Dir字段。 Path string // Args保管命令的參數，包括命令名作為第一個參數；如果為空切片或者nil，相當于無參數命令。 // // 典型用法下，Path和Args都應被Command函數設定。 Args []string // Env指定進程的環境，如為nil，則是在當前進程的環境下執行。 Env []string // Dir指定命令的工作目錄。如為空字符串，會在調用者的進程當前目錄下執行。 Dir string // Stdin指定進程的標準輸入，如為nil，進程會從空設備讀取（os.DevNull） Stdin io.Reader // Stdout和Stderr指定進程的標準輸出和標準錯誤輸出。 // // 如果任一個為nil，Run方法會將對應的文件描述符關聯到空設備（os.DevNull） // // 如果兩個字段相同，同一時間最多有一個線程可以寫入。 Stdout io.Writer Stderr io.Writer // ExtraFiles指定額外被新進程繼承的已打開文件流，不包括標準輸入、標準輸出、標準錯誤輸出。 // 如果本字段非nil，entry i會變成文件描述符3+i。 // // BUG:?在OS X 10.6系統中，子進程可能會繼承不期望的文件描述符。 // http://golang.org/issue/2603 ExtraFiles []*os.File // SysProcAttr保管可選的、各操作系統特定的sys執行屬性。 // Run方法會將它作為os.ProcAttr的Sys字段傳遞給os.StartProcess函數。 SysProcAttr *syscall.SysProcAttr // Process是底層的，只執行一次的進程。 Process *os.Process // ProcessState包含一個已經存在的進程的信息，只有在調用Wait或Run后才可用。 ProcessState *os.ProcessState // 內含隱藏或非導出字段 } ``` Cmd代表一個正在準備或者在執行中的外部命令。 ### func [Command](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L112 "View Source") ``` func Command(name string, arg ...string) *Cmd ``` 函數返回一個\*Cmd，用于使用給出的參數執行name指定的程序。返回值只設定了Path和Args兩個參數。如果name不含路徑分隔符，將使用LookPath獲取完整路徑；否則直接使用name。參數arg不應包含命令名。 Example ``` cmd := exec.Command("tr", "a-z", "A-Z") cmd.Stdin = strings.NewReader("some input") var out bytes.Buffer cmd.Stdout = &out err := cmd.Run() if err != nil { log.Fatal(err) } fmt.Printf("in all caps: %q\n", out.String()) ``` ### func (\*Cmd) [StdinPipe](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L411 "View Source") ``` func (c *Cmd) StdinPipe() (io.WriteCloser, error) ``` StdinPipe方法返回一個在命令Start后與命令標準輸入關聯的管道。Wait方法獲知命令結束后會關閉這個管道。必要時調用者可以調用Close方法來強行關閉管道，例如命令在輸入關閉后才會執行返回時需要顯式關閉管道。 ### func (\*Cmd) [StdoutPipe](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L453 "View Source") ``` func (c *Cmd) StdoutPipe() (io.ReadCloser, error) ``` StdoutPipe方法返回一個在命令Start后與命令標準輸出關聯的管道。Wait方法獲知命令結束后會關閉這個管道，一般不需要顯式的關閉該管道。但是在從管道讀取完全部數據之前調用Wait是錯誤的；同樣使用StdoutPipe方法時調用Run函數也是錯誤的。參見下例： Example ``` cmd := exec.Command("echo", "-n", `{"Name": "Bob", "Age": 32}`) stdout, err := cmd.StdoutPipe() if err != nil { log.Fatal(err) } if err := cmd.Start(); err != nil { log.Fatal(err) } var person struct { Name string Age int } if err := json.NewDecoder(stdout).Decode(&person); err != nil { log.Fatal(err) } if err := cmd.Wait(); err != nil { log.Fatal(err) } fmt.Printf("%s is %d years old\n", person.Name, person.Age) ``` ### func (\*Cmd) [StderrPipe](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L478 "View Source") ``` func (c *Cmd) StderrPipe() (io.ReadCloser, error) ``` StderrPipe方法返回一個在命令Start后與命令標準錯誤輸出關聯的管道。Wait方法獲知命令結束后會關閉這個管道，一般不需要顯式的關閉該管道。但是在從管道讀取完全部數據之前調用Wait是錯誤的；同樣使用StderrPipe方法時調用Run函數也是錯誤的。請參照StdoutPipe的例子。 ### func (\*Cmd) [Run](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L235 "View Source") ``` func (c *Cmd) Run() error ``` Run執行c包含的命令，并阻塞直到完成。如果命令成功執行，stdin、stdout、stderr的轉交沒有問題，并且返回狀態碼為0，方法的返回值為nil；如果命令沒有執行或者執行失敗，會返回\*ExitError類型的錯誤；否則返回的error可能是表示I/O問題。 ### func (\*Cmd) [Start](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L272 "View Source") ``` func (c *Cmd) Start() error ``` Start開始執行c包含的命令，但并不會等待該命令完成即返回。Wait方法會返回命令的返回狀態碼并在命令返回后釋放相關的資源。 Example ``` cmd := exec.Command("sleep", "5") err := cmd.Start() if err != nil { log.Fatal(err) } log.Printf("Waiting for command to finish...") err = cmd.Wait() log.Printf("Command finished with error: %v", err) ``` ### func (\*Cmd) [Wait](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L349 "View Source") ``` func (c *Cmd) Wait() error ``` Wait會阻塞直到該命令執行完成，該命令必須是被Start方法開始執行的。如果命令成功執行，stdin、stdout、stderr的轉交沒有問題，并且返回狀態碼為0，方法的返回值為nil；如果命令沒有執行或者執行失敗，會返回\*ExitError類型的錯誤；否則返回的error可能是表示I/O問題。Wait方法會在命令返回后釋放相關的資源。 ### func (\*Cmd) [Output](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L379 "View Source") ``` func (c *Cmd) Output() ([]byte, error) ``` 執行命令并返回標準輸出的切片。 Example ``` out, err := exec.Command("date").Output() if err != nil { log.Fatal(err) } fmt.Printf("The date is %s\n", out) ``` ### func (\*Cmd) [CombinedOutput](https://github.com/golang/go/blob/master/src/os/exec/exec.go#L391 "View Source") ``` func (c *Cmd) CombinedOutput() ([]byte, error) ``` 執行命令并返回標準輸出和錯誤輸出合并的切片。