1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package exec runs external commands. It wraps os.StartProcess to make it
6 // easier to remap stdin and stdout, connect I/O with pipes, and do other
9 // Unlike the "system" library call from C and other languages, the
10 // os/exec package intentionally does not invoke the system shell and
11 // does not expand any glob patterns or handle other expansions,
12 // pipelines, or redirections typically done by shells. The package
13 // behaves more like C's "exec" family of functions. To expand glob
14 // patterns, either call the shell directly, taking care to escape any
15 // dangerous input, or use the path/filepath package's Glob function.
16 // To expand environment variables, use package os's ExpandEnv.
18 // Note that the examples in this package assume a Unix system.
19 // They may not run on Windows, and they do not run in the Go Playground
20 // used by golang.org and godoc.org.
37 // Error is returned by LookPath when it fails to classify a file as an
40 // Name is the file name for which the error occurred.
42 // Err is the underlying error.
46 func (e *Error) Error() string {
47 return "exec: " + strconv.Quote(e.Name) + ": " + e.Err.Error()
50 func (e *Error) Unwrap() error { return e.Err }
52 // Cmd represents an external command being prepared or run.
54 // A Cmd cannot be reused after calling its Run, Output or CombinedOutput
57 // Path is the path of the command to run.
59 // This is the only field that must be set to a non-zero
60 // value. If Path is relative, it is evaluated relative
64 // Args holds command line arguments, including the command as Args[0].
65 // If the Args field is empty or nil, Run uses {Path}.
67 // In typical use, both Path and Args are set by calling Command.
70 // Env specifies the environment of the process.
71 // Each entry is of the form "key=value".
72 // If Env is nil, the new process uses the current process's
74 // If Env contains duplicate environment keys, only the last
75 // value in the slice for each duplicate key is used.
76 // As a special case on Windows, SYSTEMROOT is always added if
77 // missing and not explicitly set to the empty string.
80 // Dir specifies the working directory of the command.
81 // If Dir is the empty string, Run runs the command in the
82 // calling process's current directory.
85 // Stdin specifies the process's standard input.
87 // If Stdin is nil, the process reads from the null device (os.DevNull).
89 // If Stdin is an *os.File, the process's standard input is connected
90 // directly to that file.
92 // Otherwise, during the execution of the command a separate
93 // goroutine reads from Stdin and delivers that data to the command
94 // over a pipe. In this case, Wait does not complete until the goroutine
95 // stops copying, either because it has reached the end of Stdin
96 // (EOF or a read error) or because writing to the pipe returned an error.
99 // Stdout and Stderr specify the process's standard output and error.
101 // If either is nil, Run connects the corresponding file descriptor
102 // to the null device (os.DevNull).
104 // If either is an *os.File, the corresponding output from the process
105 // is connected directly to that file.
107 // Otherwise, during the execution of the command a separate goroutine
108 // reads from the process over a pipe and delivers that data to the
109 // corresponding Writer. In this case, Wait does not complete until the
110 // goroutine reaches EOF or encounters an error.
112 // If Stdout and Stderr are the same writer, and have a type that can
113 // be compared with ==, at most one goroutine at a time will call Write.
117 // ExtraFiles specifies additional open files to be inherited by the
118 // new process. It does not include standard input, standard output, or
119 // standard error. If non-nil, entry i becomes file descriptor 3+i.
121 // ExtraFiles is not supported on Windows.
122 ExtraFiles []*os.File
124 // SysProcAttr holds optional, operating system-specific attributes.
125 // Run passes it to os.StartProcess as the os.ProcAttr's Sys field.
126 SysProcAttr *syscall.SysProcAttr
128 // Process is the underlying process, once started.
131 // ProcessState contains information about an exited process,
132 // available after a call to Wait or Run.
133 ProcessState *os.ProcessState
135 ctx context.Context // nil means none
136 lookPathErr error // LookPath error, if any.
137 finished bool // when Wait was called
138 childFiles []*os.File
139 closeAfterStart []io.Closer
140 closeAfterWait []io.Closer
141 goroutine []func() error
142 errch chan error // one send per goroutine
143 waitDone chan struct{}
146 // Command returns the Cmd struct to execute the named program with
147 // the given arguments.
149 // It sets only the Path and Args in the returned structure.
151 // If name contains no path separators, Command uses LookPath to
152 // resolve name to a complete path if possible. Otherwise it uses name
155 // The returned Cmd's Args field is constructed from the command name
156 // followed by the elements of arg, so arg should not include the
157 // command name itself. For example, Command("echo", "hello").
158 // Args[0] is always name, not the possibly resolved Path.
160 // On Windows, processes receive the whole command line as a single string
161 // and do their own parsing. Command combines and quotes Args into a command
162 // line string with an algorithm compatible with applications using
163 // CommandLineToArgvW (which is the most common way). Notable exceptions are
164 // msiexec.exe and cmd.exe (and thus, all batch files), which have a different
165 // unquoting algorithm. In these or other similar cases, you can do the
166 // quoting yourself and provide the full command line in SysProcAttr.CmdLine,
167 // leaving Args empty.
168 func Command(name string, arg ...string) *Cmd {
171 Args: append([]string{name}, arg...),
173 if filepath.Base(name) == name {
174 if lp, err := LookPath(name); err != nil {
175 cmd.lookPathErr = err
183 // CommandContext is like Command but includes a context.
185 // The provided context is used to kill the process (by calling
186 // os.Process.Kill) if the context becomes done before the command
187 // completes on its own.
188 func CommandContext(ctx context.Context, name string, arg ...string) *Cmd {
192 cmd := Command(name, arg...)
197 // String returns a human-readable description of c.
198 // It is intended only for debugging.
199 // In particular, it is not suitable for use as input to a shell.
200 // The output of String may vary across Go releases.
201 func (c *Cmd) String() string {
202 if c.lookPathErr != nil {
203 // failed to resolve path; report the original requested path (plus args)
204 return strings.Join(c.Args, " ")
206 // report the exact executable path (plus args)
207 b := new(strings.Builder)
208 b.WriteString(c.Path)
209 for _, a := range c.Args[1:] {
216 // interfaceEqual protects against panics from doing equality tests on
217 // two interfaces with non-comparable underlying types.
218 func interfaceEqual(a, b interface{}) bool {
225 func (c *Cmd) envv() []string {
232 func (c *Cmd) argv() []string {
236 return []string{c.Path}
239 // skipStdinCopyError optionally specifies a function which reports
240 // whether the provided stdin copy error should be ignored.
241 var skipStdinCopyError func(error) bool
243 func (c *Cmd) stdin() (f *os.File, err error) {
245 f, err = os.Open(os.DevNull)
249 c.closeAfterStart = append(c.closeAfterStart, f)
253 if f, ok := c.Stdin.(*os.File); ok {
257 pr, pw, err := os.Pipe()
262 c.closeAfterStart = append(c.closeAfterStart, pr)
263 c.closeAfterWait = append(c.closeAfterWait, pw)
264 c.goroutine = append(c.goroutine, func() error {
265 _, err := io.Copy(pw, c.Stdin)
266 if skip := skipStdinCopyError; skip != nil && skip(err) {
269 if err1 := pw.Close(); err == nil {
277 func (c *Cmd) stdout() (f *os.File, err error) {
278 return c.writerDescriptor(c.Stdout)
281 func (c *Cmd) stderr() (f *os.File, err error) {
282 if c.Stderr != nil && interfaceEqual(c.Stderr, c.Stdout) {
283 return c.childFiles[1], nil
285 return c.writerDescriptor(c.Stderr)
288 func (c *Cmd) writerDescriptor(w io.Writer) (f *os.File, err error) {
290 f, err = os.OpenFile(os.DevNull, os.O_WRONLY, 0)
294 c.closeAfterStart = append(c.closeAfterStart, f)
298 if f, ok := w.(*os.File); ok {
302 pr, pw, err := os.Pipe()
307 c.closeAfterStart = append(c.closeAfterStart, pw)
308 c.closeAfterWait = append(c.closeAfterWait, pr)
309 c.goroutine = append(c.goroutine, func() error {
310 _, err := io.Copy(w, pr)
311 pr.Close() // in case io.Copy stopped due to write error
317 func (c *Cmd) closeDescriptors(closers []io.Closer) {
318 for _, fd := range closers {
323 // Run starts the specified command and waits for it to complete.
325 // The returned error is nil if the command runs, has no problems
326 // copying stdin, stdout, and stderr, and exits with a zero exit
329 // If the command starts but does not complete successfully, the error is of
330 // type *ExitError. Other error types may be returned for other situations.
332 // If the calling goroutine has locked the operating system thread
333 // with runtime.LockOSThread and modified any inheritable OS-level
334 // thread state (for example, Linux or Plan 9 name spaces), the new
335 // process will inherit the caller's thread state.
336 func (c *Cmd) Run() error {
337 if err := c.Start(); err != nil {
343 // lookExtensions finds windows executable by its dir and path.
344 // It uses LookPath to try appropriate extensions.
345 // lookExtensions does not search PATH, instead it converts `prog` into `.\prog`.
346 func lookExtensions(path, dir string) (string, error) {
347 if filepath.Base(path) == path {
348 path = filepath.Join(".", path)
351 return LookPath(path)
353 if filepath.VolumeName(path) != "" {
354 return LookPath(path)
356 if len(path) > 1 && os.IsPathSeparator(path[0]) {
357 return LookPath(path)
359 dirandpath := filepath.Join(dir, path)
360 // We assume that LookPath will only add file extension.
361 lp, err := LookPath(dirandpath)
365 ext := strings.TrimPrefix(lp, dirandpath)
366 return path + ext, nil
369 // Start starts the specified command but does not wait for it to complete.
371 // If Start returns successfully, the c.Process field will be set.
373 // The Wait method will return the exit code and release associated resources
374 // once the command exits.
375 func (c *Cmd) Start() error {
376 if c.lookPathErr != nil {
377 c.closeDescriptors(c.closeAfterStart)
378 c.closeDescriptors(c.closeAfterWait)
381 if runtime.GOOS == "windows" {
382 lp, err := lookExtensions(c.Path, c.Dir)
384 c.closeDescriptors(c.closeAfterStart)
385 c.closeDescriptors(c.closeAfterWait)
390 if c.Process != nil {
391 return errors.New("exec: already started")
396 c.closeDescriptors(c.closeAfterStart)
397 c.closeDescriptors(c.closeAfterWait)
403 c.childFiles = make([]*os.File, 0, 3+len(c.ExtraFiles))
404 type F func(*Cmd) (*os.File, error)
405 for _, setupFd := range []F{(*Cmd).stdin, (*Cmd).stdout, (*Cmd).stderr} {
406 fd, err := setupFd(c)
408 c.closeDescriptors(c.closeAfterStart)
409 c.closeDescriptors(c.closeAfterWait)
412 c.childFiles = append(c.childFiles, fd)
414 c.childFiles = append(c.childFiles, c.ExtraFiles...)
417 c.Process, err = os.StartProcess(c.Path, c.argv(), &os.ProcAttr{
420 Env: addCriticalEnv(dedupEnv(c.envv())),
424 c.closeDescriptors(c.closeAfterStart)
425 c.closeDescriptors(c.closeAfterWait)
429 c.closeDescriptors(c.closeAfterStart)
431 // Don't allocate the channel unless there are goroutines to fire.
432 if len(c.goroutine) > 0 {
433 c.errch = make(chan error, len(c.goroutine))
434 for _, fn := range c.goroutine {
435 go func(fn func() error) {
442 c.waitDone = make(chan struct{})
455 // An ExitError reports an unsuccessful exit by a command.
456 type ExitError struct {
459 // Stderr holds a subset of the standard error output from the
460 // Cmd.Output method if standard error was not otherwise being
463 // If the error output is long, Stderr may contain only a prefix
464 // and suffix of the output, with the middle replaced with
465 // text about the number of omitted bytes.
467 // Stderr is provided for debugging, for inclusion in error messages.
468 // Users with other needs should redirect Cmd.Stderr as needed.
472 func (e *ExitError) Error() string {
473 return e.ProcessState.String()
476 // Wait waits for the command to exit and waits for any copying to
477 // stdin or copying from stdout or stderr to complete.
479 // The command must have been started by Start.
481 // The returned error is nil if the command runs, has no problems
482 // copying stdin, stdout, and stderr, and exits with a zero exit
485 // If the command fails to run or doesn't complete successfully, the
486 // error is of type *ExitError. Other error types may be
487 // returned for I/O problems.
489 // If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits
490 // for the respective I/O loop copying to or from the process to complete.
492 // Wait releases any resources associated with the Cmd.
493 func (c *Cmd) Wait() error {
494 if c.Process == nil {
495 return errors.New("exec: not started")
498 return errors.New("exec: Wait was already called")
502 state, err := c.Process.Wait()
503 if c.waitDone != nil {
506 c.ProcessState = state
509 for range c.goroutine {
510 if err := <-c.errch; err != nil && copyError == nil {
515 c.closeDescriptors(c.closeAfterWait)
519 } else if !state.Success() {
520 return &ExitError{ProcessState: state}
526 // Output runs the command and returns its standard output.
527 // Any returned error will usually be of type *ExitError.
528 // If c.Stderr was nil, Output populates ExitError.Stderr.
529 func (c *Cmd) Output() ([]byte, error) {
531 return nil, errors.New("exec: Stdout already set")
533 var stdout bytes.Buffer
536 captureErr := c.Stderr == nil
538 c.Stderr = &prefixSuffixSaver{N: 32 << 10}
542 if err != nil && captureErr {
543 if ee, ok := err.(*ExitError); ok {
544 ee.Stderr = c.Stderr.(*prefixSuffixSaver).Bytes()
547 return stdout.Bytes(), err
550 // CombinedOutput runs the command and returns its combined standard
551 // output and standard error.
552 func (c *Cmd) CombinedOutput() ([]byte, error) {
554 return nil, errors.New("exec: Stdout already set")
557 return nil, errors.New("exec: Stderr already set")
563 return b.Bytes(), err
566 // StdinPipe returns a pipe that will be connected to the command's
567 // standard input when the command starts.
568 // The pipe will be closed automatically after Wait sees the command exit.
569 // A caller need only call Close to force the pipe to close sooner.
570 // For example, if the command being run will not exit until standard input
571 // is closed, the caller must close the pipe.
572 func (c *Cmd) StdinPipe() (io.WriteCloser, error) {
574 return nil, errors.New("exec: Stdin already set")
576 if c.Process != nil {
577 return nil, errors.New("exec: StdinPipe after process started")
579 pr, pw, err := os.Pipe()
584 c.closeAfterStart = append(c.closeAfterStart, pr)
585 wc := &closeOnce{File: pw}
586 c.closeAfterWait = append(c.closeAfterWait, wc)
590 type closeOnce struct {
597 func (c *closeOnce) Close() error {
602 func (c *closeOnce) close() {
603 c.err = c.File.Close()
606 // StdoutPipe returns a pipe that will be connected to the command's
607 // standard output when the command starts.
609 // Wait will close the pipe after seeing the command exit, so most callers
610 // need not close the pipe themselves. It is thus incorrect to call Wait
611 // before all reads from the pipe have completed.
612 // For the same reason, it is incorrect to call Run when using StdoutPipe.
613 // See the example for idiomatic usage.
614 func (c *Cmd) StdoutPipe() (io.ReadCloser, error) {
616 return nil, errors.New("exec: Stdout already set")
618 if c.Process != nil {
619 return nil, errors.New("exec: StdoutPipe after process started")
621 pr, pw, err := os.Pipe()
626 c.closeAfterStart = append(c.closeAfterStart, pw)
627 c.closeAfterWait = append(c.closeAfterWait, pr)
631 // StderrPipe returns a pipe that will be connected to the command's
632 // standard error when the command starts.
634 // Wait will close the pipe after seeing the command exit, so most callers
635 // need not close the pipe themselves. It is thus incorrect to call Wait
636 // before all reads from the pipe have completed.
637 // For the same reason, it is incorrect to use Run when using StderrPipe.
638 // See the StdoutPipe example for idiomatic usage.
639 func (c *Cmd) StderrPipe() (io.ReadCloser, error) {
641 return nil, errors.New("exec: Stderr already set")
643 if c.Process != nil {
644 return nil, errors.New("exec: StderrPipe after process started")
646 pr, pw, err := os.Pipe()
651 c.closeAfterStart = append(c.closeAfterStart, pw)
652 c.closeAfterWait = append(c.closeAfterWait, pr)
656 // prefixSuffixSaver is an io.Writer which retains the first N bytes
657 // and the last N bytes written to it. The Bytes() methods reconstructs
658 // it with a pretty error message.
659 type prefixSuffixSaver struct {
660 N int // max size of prefix or suffix
662 suffix []byte // ring buffer once len(suffix) == N
663 suffixOff int // offset to write into suffix
666 // TODO(bradfitz): we could keep one large []byte and use part of it for
667 // the prefix, reserve space for the '... Omitting N bytes ...' message,
668 // then the ring buffer suffix, and just rearrange the ring buffer
669 // suffix when Bytes() is called, but it doesn't seem worth it for
670 // now just for error messages. It's only ~64KB anyway.
673 func (w *prefixSuffixSaver) Write(p []byte) (n int, err error) {
675 p = w.fill(&w.prefix, p)
677 // Only keep the last w.N bytes of suffix data.
678 if overage := len(p) - w.N; overage > 0 {
680 w.skipped += int64(overage)
682 p = w.fill(&w.suffix, p)
684 // w.suffix is full now if p is non-empty. Overwrite it in a circle.
685 for len(p) > 0 { // 0, 1, or 2 iterations.
686 n := copy(w.suffix[w.suffixOff:], p)
688 w.skipped += int64(n)
690 if w.suffixOff == w.N {
697 // fill appends up to len(p) bytes of p to *dst, such that *dst does not
698 // grow larger than w.N. It returns the un-appended suffix of p.
699 func (w *prefixSuffixSaver) fill(dst *[]byte, p []byte) (pRemain []byte) {
700 if remain := w.N - len(*dst); remain > 0 {
701 add := minInt(len(p), remain)
702 *dst = append(*dst, p[:add]...)
708 func (w *prefixSuffixSaver) Bytes() []byte {
713 return append(w.prefix, w.suffix...)
716 buf.Grow(len(w.prefix) + len(w.suffix) + 50)
718 buf.WriteString("\n... omitting ")
719 buf.WriteString(strconv.FormatInt(w.skipped, 10))
720 buf.WriteString(" bytes ...\n")
721 buf.Write(w.suffix[w.suffixOff:])
722 buf.Write(w.suffix[:w.suffixOff])
726 func minInt(a, b int) int {
733 // dedupEnv returns a copy of env with any duplicates removed, in favor of
735 // Items not of the normal environment "key=value" form are preserved unchanged.
736 func dedupEnv(env []string) []string {
737 return dedupEnvCase(runtime.GOOS == "windows", env)
740 // dedupEnvCase is dedupEnv with a case option for testing.
741 // If caseInsensitive is true, the case of keys is ignored.
742 func dedupEnvCase(caseInsensitive bool, env []string) []string {
743 out := make([]string, 0, len(env))
744 saw := make(map[string]int, len(env)) // key => index into out
745 for _, kv := range env {
746 eq := strings.Index(kv, "=")
748 out = append(out, kv)
753 k = strings.ToLower(k)
755 if dupIdx, isDup := saw[k]; isDup {
760 out = append(out, kv)
765 // addCriticalEnv adds any critical environment variables that are required
766 // (or at least almost always required) on the operating system.
767 // Currently this is only used for Windows.
768 func addCriticalEnv(env []string) []string {
769 if runtime.GOOS != "windows" {
772 for _, kv := range env {
773 eq := strings.Index(kv, "=")
778 if strings.EqualFold(k, "SYSTEMROOT") {
779 // We already have it.
783 return append(env, "SYSTEMROOT="+os.Getenv("SYSTEMROOT"))