github.com/gocuntian/go@v0.0.0-20160610041250-fee02d270bf8/src/os/exec/exec.go (about) 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. 4 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 7 // adjustments. 8 // 9 // Note that the examples in this package assume a Unix system. 10 // They may not run on Windows, and they do not run in the Go Playground 11 // used by golang.org and godoc.org. 12 package exec 13 14 import ( 15 "bytes" 16 "context" 17 "errors" 18 "io" 19 "os" 20 "path/filepath" 21 "runtime" 22 "strconv" 23 "strings" 24 "sync" 25 "syscall" 26 ) 27 28 // Error records the name of a binary that failed to be executed 29 // and the reason it failed. 30 type Error struct { 31 Name string 32 Err error 33 } 34 35 func (e *Error) Error() string { 36 return "exec: " + strconv.Quote(e.Name) + ": " + e.Err.Error() 37 } 38 39 // Cmd represents an external command being prepared or run. 40 // 41 // A Cmd cannot be reused after calling its Run, Output or CombinedOutput 42 // methods. 43 type Cmd struct { 44 // Path is the path of the command to run. 45 // 46 // This is the only field that must be set to a non-zero 47 // value. If Path is relative, it is evaluated relative 48 // to Dir. 49 Path string 50 51 // Args holds command line arguments, including the command as Args[0]. 52 // If the Args field is empty or nil, Run uses {Path}. 53 // 54 // In typical use, both Path and Args are set by calling Command. 55 Args []string 56 57 // Env specifies the environment of the process. 58 // If Env is nil, Run uses the current process's environment. 59 Env []string 60 61 // Dir specifies the working directory of the command. 62 // If Dir is the empty string, Run runs the command in the 63 // calling process's current directory. 64 Dir string 65 66 // Stdin specifies the process's standard input. 67 // If Stdin is nil, the process reads from the null device (os.DevNull). 68 // If Stdin is an *os.File, the process's standard input is connected 69 // directly to that file. 70 // Otherwise, during the execution of the command a separate 71 // goroutine reads from Stdin and delivers that data to the command 72 // over a pipe. In this case, Wait does not complete until the goroutine 73 // stops copying, either because it has reached the end of Stdin 74 // (EOF or a read error) or because writing to the pipe returned an error. 75 Stdin io.Reader 76 77 // Stdout and Stderr specify the process's standard output and error. 78 // 79 // If either is nil, Run connects the corresponding file descriptor 80 // to the null device (os.DevNull). 81 // 82 // If Stdout and Stderr are the same writer, at most one 83 // goroutine at a time will call Write. 84 Stdout io.Writer 85 Stderr io.Writer 86 87 // ExtraFiles specifies additional open files to be inherited by the 88 // new process. It does not include standard input, standard output, or 89 // standard error. If non-nil, entry i becomes file descriptor 3+i. 90 // 91 // BUG(rsc): On OS X 10.6, child processes may sometimes inherit unwanted fds. 92 // https://golang.org/issue/2603 93 ExtraFiles []*os.File 94 95 // SysProcAttr holds optional, operating system-specific attributes. 96 // Run passes it to os.StartProcess as the os.ProcAttr's Sys field. 97 SysProcAttr *syscall.SysProcAttr 98 99 // Process is the underlying process, once started. 100 Process *os.Process 101 102 // ProcessState contains information about an exited process, 103 // available after a call to Wait or Run. 104 ProcessState *os.ProcessState 105 106 ctx context.Context // nil means none 107 lookPathErr error // LookPath error, if any. 108 finished bool // when Wait was called 109 childFiles []*os.File 110 closeAfterStart []io.Closer 111 closeAfterWait []io.Closer 112 goroutine []func() error 113 errch chan error // one send per goroutine 114 } 115 116 // Command returns the Cmd struct to execute the named program with 117 // the given arguments. 118 // 119 // It sets only the Path and Args in the returned structure. 120 // 121 // If name contains no path separators, Command uses LookPath to 122 // resolve the path to a complete name if possible. Otherwise it uses 123 // name directly. 124 // 125 // The returned Cmd's Args field is constructed from the command name 126 // followed by the elements of arg, so arg should not include the 127 // command name itself. For example, Command("echo", "hello") 128 func Command(name string, arg ...string) *Cmd { 129 cmd := &Cmd{ 130 Path: name, 131 Args: append([]string{name}, arg...), 132 } 133 if filepath.Base(name) == name { 134 if lp, err := LookPath(name); err != nil { 135 cmd.lookPathErr = err 136 } else { 137 cmd.Path = lp 138 } 139 } 140 return cmd 141 } 142 143 // CommandContext is like Command but includes a context. 144 // 145 // The provided context is used to kill the process (by calling 146 // os.Process.Kill) if the context becomes done before the command 147 // completes on its own. 148 func CommandContext(ctx context.Context, name string, arg ...string) *Cmd { 149 if ctx == nil { 150 panic("nil Context") 151 } 152 cmd := Command(name, arg...) 153 cmd.ctx = ctx 154 return cmd 155 } 156 157 // interfaceEqual protects against panics from doing equality tests on 158 // two interfaces with non-comparable underlying types. 159 func interfaceEqual(a, b interface{}) bool { 160 defer func() { 161 recover() 162 }() 163 return a == b 164 } 165 166 func (c *Cmd) envv() []string { 167 if c.Env != nil { 168 return c.Env 169 } 170 return os.Environ() 171 } 172 173 func (c *Cmd) argv() []string { 174 if len(c.Args) > 0 { 175 return c.Args 176 } 177 return []string{c.Path} 178 } 179 180 // skipStdinCopyError optionally specifies a function which reports 181 // whether the provided the stdin copy error should be ignored. 182 // It is non-nil everywhere but Plan 9, which lacks EPIPE. See exec_posix.go. 183 var skipStdinCopyError func(error) bool 184 185 func (c *Cmd) stdin() (f *os.File, err error) { 186 if c.Stdin == nil { 187 f, err = os.Open(os.DevNull) 188 if err != nil { 189 return 190 } 191 c.closeAfterStart = append(c.closeAfterStart, f) 192 return 193 } 194 195 if f, ok := c.Stdin.(*os.File); ok { 196 return f, nil 197 } 198 199 pr, pw, err := os.Pipe() 200 if err != nil { 201 return 202 } 203 204 c.closeAfterStart = append(c.closeAfterStart, pr) 205 c.closeAfterWait = append(c.closeAfterWait, pw) 206 c.goroutine = append(c.goroutine, func() error { 207 _, err := io.Copy(pw, c.Stdin) 208 if skip := skipStdinCopyError; skip != nil && skip(err) { 209 err = nil 210 } 211 if err1 := pw.Close(); err == nil { 212 err = err1 213 } 214 return err 215 }) 216 return pr, nil 217 } 218 219 func (c *Cmd) stdout() (f *os.File, err error) { 220 return c.writerDescriptor(c.Stdout) 221 } 222 223 func (c *Cmd) stderr() (f *os.File, err error) { 224 if c.Stderr != nil && interfaceEqual(c.Stderr, c.Stdout) { 225 return c.childFiles[1], nil 226 } 227 return c.writerDescriptor(c.Stderr) 228 } 229 230 func (c *Cmd) writerDescriptor(w io.Writer) (f *os.File, err error) { 231 if w == nil { 232 f, err = os.OpenFile(os.DevNull, os.O_WRONLY, 0) 233 if err != nil { 234 return 235 } 236 c.closeAfterStart = append(c.closeAfterStart, f) 237 return 238 } 239 240 if f, ok := w.(*os.File); ok { 241 return f, nil 242 } 243 244 pr, pw, err := os.Pipe() 245 if err != nil { 246 return 247 } 248 249 c.closeAfterStart = append(c.closeAfterStart, pw) 250 c.closeAfterWait = append(c.closeAfterWait, pr) 251 c.goroutine = append(c.goroutine, func() error { 252 _, err := io.Copy(w, pr) 253 pr.Close() // in case io.Copy stopped due to write error 254 return err 255 }) 256 return pw, nil 257 } 258 259 func (c *Cmd) closeDescriptors(closers []io.Closer) { 260 for _, fd := range closers { 261 fd.Close() 262 } 263 } 264 265 // Run starts the specified command and waits for it to complete. 266 // 267 // The returned error is nil if the command runs, has no problems 268 // copying stdin, stdout, and stderr, and exits with a zero exit 269 // status. 270 // 271 // If the command fails to run or doesn't complete successfully, the 272 // error is of type *ExitError. Other error types may be 273 // returned for I/O problems. 274 func (c *Cmd) Run() error { 275 if err := c.Start(); err != nil { 276 return err 277 } 278 return c.Wait() 279 } 280 281 // lookExtensions finds windows executable by its dir and path. 282 // It uses LookPath to try appropriate extensions. 283 // lookExtensions does not search PATH, instead it converts `prog` into `.\prog`. 284 func lookExtensions(path, dir string) (string, error) { 285 if filepath.Base(path) == path { 286 path = filepath.Join(".", path) 287 } 288 if dir == "" { 289 return LookPath(path) 290 } 291 if filepath.VolumeName(path) != "" { 292 return LookPath(path) 293 } 294 if len(path) > 1 && os.IsPathSeparator(path[0]) { 295 return LookPath(path) 296 } 297 dirandpath := filepath.Join(dir, path) 298 // We assume that LookPath will only add file extension. 299 lp, err := LookPath(dirandpath) 300 if err != nil { 301 return "", err 302 } 303 ext := strings.TrimPrefix(lp, dirandpath) 304 return path + ext, nil 305 } 306 307 // Start starts the specified command but does not wait for it to complete. 308 // 309 // The Wait method will return the exit code and release associated resources 310 // once the command exits. 311 func (c *Cmd) Start() error { 312 if c.lookPathErr != nil { 313 c.closeDescriptors(c.closeAfterStart) 314 c.closeDescriptors(c.closeAfterWait) 315 return c.lookPathErr 316 } 317 if runtime.GOOS == "windows" { 318 lp, err := lookExtensions(c.Path, c.Dir) 319 if err != nil { 320 c.closeDescriptors(c.closeAfterStart) 321 c.closeDescriptors(c.closeAfterWait) 322 return err 323 } 324 c.Path = lp 325 } 326 if c.Process != nil { 327 return errors.New("exec: already started") 328 } 329 330 type F func(*Cmd) (*os.File, error) 331 for _, setupFd := range []F{(*Cmd).stdin, (*Cmd).stdout, (*Cmd).stderr} { 332 fd, err := setupFd(c) 333 if err != nil { 334 c.closeDescriptors(c.closeAfterStart) 335 c.closeDescriptors(c.closeAfterWait) 336 return err 337 } 338 c.childFiles = append(c.childFiles, fd) 339 } 340 c.childFiles = append(c.childFiles, c.ExtraFiles...) 341 342 var err error 343 c.Process, err = os.StartProcess(c.Path, c.argv(), &os.ProcAttr{ 344 Dir: c.Dir, 345 Files: c.childFiles, 346 Env: c.envv(), 347 Sys: c.SysProcAttr, 348 }) 349 if err != nil { 350 c.closeDescriptors(c.closeAfterStart) 351 c.closeDescriptors(c.closeAfterWait) 352 return err 353 } 354 355 c.closeDescriptors(c.closeAfterStart) 356 357 c.errch = make(chan error, len(c.goroutine)) 358 for _, fn := range c.goroutine { 359 go func(fn func() error) { 360 c.errch <- fn() 361 }(fn) 362 } 363 364 return nil 365 } 366 367 // An ExitError reports an unsuccessful exit by a command. 368 type ExitError struct { 369 *os.ProcessState 370 371 // Stderr holds a subset of the standard error output from the 372 // Cmd.Output method if standard error was not otherwise being 373 // collected. 374 // 375 // If the error output is long, Stderr may contain only a prefix 376 // and suffix of the output, with the middle replaced with 377 // text about the number of omitted bytes. 378 // 379 // Stderr is provided for debugging, for inclusion in error messages. 380 // Users with other needs should redirect Cmd.Stderr as needed. 381 Stderr []byte 382 } 383 384 func (e *ExitError) Error() string { 385 return e.ProcessState.String() 386 } 387 388 // Wait waits for the command to exit. 389 // It must have been started by Start. 390 // 391 // The returned error is nil if the command runs, has no problems 392 // copying stdin, stdout, and stderr, and exits with a zero exit 393 // status. 394 // 395 // If the command fails to run or doesn't complete successfully, the 396 // error is of type *ExitError. Other error types may be 397 // returned for I/O problems. 398 // 399 // If c.Stdin is not an *os.File, Wait also waits for the I/O loop 400 // copying from c.Stdin into the process's standard input 401 // to complete. 402 // 403 // Wait releases any resources associated with the Cmd. 404 func (c *Cmd) Wait() error { 405 if c.Process == nil { 406 return errors.New("exec: not started") 407 } 408 if c.finished { 409 return errors.New("exec: Wait was already called") 410 } 411 c.finished = true 412 413 var waitDone chan struct{} 414 if c.ctx != nil { 415 waitDone = make(chan struct{}) 416 go func() { 417 select { 418 case <-c.ctx.Done(): 419 c.Process.Kill() 420 case <-waitDone: 421 } 422 }() 423 } 424 state, err := c.Process.Wait() 425 if waitDone != nil { 426 close(waitDone) 427 } 428 c.ProcessState = state 429 430 var copyError error 431 for range c.goroutine { 432 if err := <-c.errch; err != nil && copyError == nil { 433 copyError = err 434 } 435 } 436 437 c.closeDescriptors(c.closeAfterWait) 438 439 if err != nil { 440 return err 441 } else if !state.Success() { 442 return &ExitError{ProcessState: state} 443 } 444 445 return copyError 446 } 447 448 // Output runs the command and returns its standard output. 449 // Any returned error will usually be of type *ExitError. 450 // If c.Stderr was nil, Output populates ExitError.Stderr. 451 func (c *Cmd) Output() ([]byte, error) { 452 if c.Stdout != nil { 453 return nil, errors.New("exec: Stdout already set") 454 } 455 var stdout bytes.Buffer 456 c.Stdout = &stdout 457 458 captureErr := c.Stderr == nil 459 if captureErr { 460 c.Stderr = &prefixSuffixSaver{N: 32 << 10} 461 } 462 463 err := c.Run() 464 if err != nil && captureErr { 465 if ee, ok := err.(*ExitError); ok { 466 ee.Stderr = c.Stderr.(*prefixSuffixSaver).Bytes() 467 } 468 } 469 return stdout.Bytes(), err 470 } 471 472 // CombinedOutput runs the command and returns its combined standard 473 // output and standard error. 474 func (c *Cmd) CombinedOutput() ([]byte, error) { 475 if c.Stdout != nil { 476 return nil, errors.New("exec: Stdout already set") 477 } 478 if c.Stderr != nil { 479 return nil, errors.New("exec: Stderr already set") 480 } 481 var b bytes.Buffer 482 c.Stdout = &b 483 c.Stderr = &b 484 err := c.Run() 485 return b.Bytes(), err 486 } 487 488 // StdinPipe returns a pipe that will be connected to the command's 489 // standard input when the command starts. 490 // The pipe will be closed automatically after Wait sees the command exit. 491 // A caller need only call Close to force the pipe to close sooner. 492 // For example, if the command being run will not exit until standard input 493 // is closed, the caller must close the pipe. 494 func (c *Cmd) StdinPipe() (io.WriteCloser, error) { 495 if c.Stdin != nil { 496 return nil, errors.New("exec: Stdin already set") 497 } 498 if c.Process != nil { 499 return nil, errors.New("exec: StdinPipe after process started") 500 } 501 pr, pw, err := os.Pipe() 502 if err != nil { 503 return nil, err 504 } 505 c.Stdin = pr 506 c.closeAfterStart = append(c.closeAfterStart, pr) 507 wc := &closeOnce{File: pw} 508 c.closeAfterWait = append(c.closeAfterWait, wc) 509 return wc, nil 510 } 511 512 type closeOnce struct { 513 *os.File 514 515 once sync.Once 516 err error 517 } 518 519 func (c *closeOnce) Close() error { 520 c.once.Do(c.close) 521 return c.err 522 } 523 524 func (c *closeOnce) close() { 525 c.err = c.File.Close() 526 } 527 528 // StdoutPipe returns a pipe that will be connected to the command's 529 // standard output when the command starts. 530 // 531 // Wait will close the pipe after seeing the command exit, so most callers 532 // need not close the pipe themselves; however, an implication is that 533 // it is incorrect to call Wait before all reads from the pipe have completed. 534 // For the same reason, it is incorrect to call Run when using StdoutPipe. 535 // See the example for idiomatic usage. 536 func (c *Cmd) StdoutPipe() (io.ReadCloser, error) { 537 if c.Stdout != nil { 538 return nil, errors.New("exec: Stdout already set") 539 } 540 if c.Process != nil { 541 return nil, errors.New("exec: StdoutPipe after process started") 542 } 543 pr, pw, err := os.Pipe() 544 if err != nil { 545 return nil, err 546 } 547 c.Stdout = pw 548 c.closeAfterStart = append(c.closeAfterStart, pw) 549 c.closeAfterWait = append(c.closeAfterWait, pr) 550 return pr, nil 551 } 552 553 // StderrPipe returns a pipe that will be connected to the command's 554 // standard error when the command starts. 555 // 556 // Wait will close the pipe after seeing the command exit, so most callers 557 // need not close the pipe themselves; however, an implication is that 558 // it is incorrect to call Wait before all reads from the pipe have completed. 559 // For the same reason, it is incorrect to use Run when using StderrPipe. 560 // See the StdoutPipe example for idiomatic usage. 561 func (c *Cmd) StderrPipe() (io.ReadCloser, error) { 562 if c.Stderr != nil { 563 return nil, errors.New("exec: Stderr already set") 564 } 565 if c.Process != nil { 566 return nil, errors.New("exec: StderrPipe after process started") 567 } 568 pr, pw, err := os.Pipe() 569 if err != nil { 570 return nil, err 571 } 572 c.Stderr = pw 573 c.closeAfterStart = append(c.closeAfterStart, pw) 574 c.closeAfterWait = append(c.closeAfterWait, pr) 575 return pr, nil 576 } 577 578 // prefixSuffixSaver is an io.Writer which retains the first N bytes 579 // and the last N bytes written to it. The Bytes() methods reconstructs 580 // it with a pretty error message. 581 type prefixSuffixSaver struct { 582 N int // max size of prefix or suffix 583 prefix []byte 584 suffix []byte // ring buffer once len(suffix) == N 585 suffixOff int // offset to write into suffix 586 skipped int64 587 588 // TODO(bradfitz): we could keep one large []byte and use part of it for 589 // the prefix, reserve space for the '... Omitting N bytes ...' message, 590 // then the ring buffer suffix, and just rearrange the ring buffer 591 // suffix when Bytes() is called, but it doesn't seem worth it for 592 // now just for error messages. It's only ~64KB anyway. 593 } 594 595 func (w *prefixSuffixSaver) Write(p []byte) (n int, err error) { 596 lenp := len(p) 597 p = w.fill(&w.prefix, p) 598 599 // Only keep the last w.N bytes of suffix data. 600 if overage := len(p) - w.N; overage > 0 { 601 p = p[overage:] 602 w.skipped += int64(overage) 603 } 604 p = w.fill(&w.suffix, p) 605 606 // w.suffix is full now if p is non-empty. Overwrite it in a circle. 607 for len(p) > 0 { // 0, 1, or 2 iterations. 608 n := copy(w.suffix[w.suffixOff:], p) 609 p = p[n:] 610 w.skipped += int64(n) 611 w.suffixOff += n 612 if w.suffixOff == w.N { 613 w.suffixOff = 0 614 } 615 } 616 return lenp, nil 617 } 618 619 // fill appends up to len(p) bytes of p to *dst, such that *dst does not 620 // grow larger than w.N. It returns the un-appended suffix of p. 621 func (w *prefixSuffixSaver) fill(dst *[]byte, p []byte) (pRemain []byte) { 622 if remain := w.N - len(*dst); remain > 0 { 623 add := minInt(len(p), remain) 624 *dst = append(*dst, p[:add]...) 625 p = p[add:] 626 } 627 return p 628 } 629 630 func (w *prefixSuffixSaver) Bytes() []byte { 631 if w.suffix == nil { 632 return w.prefix 633 } 634 if w.skipped == 0 { 635 return append(w.prefix, w.suffix...) 636 } 637 var buf bytes.Buffer 638 buf.Grow(len(w.prefix) + len(w.suffix) + 50) 639 buf.Write(w.prefix) 640 buf.WriteString("\n... omitting ") 641 buf.WriteString(strconv.FormatInt(w.skipped, 10)) 642 buf.WriteString(" bytes ...\n") 643 buf.Write(w.suffix[w.suffixOff:]) 644 buf.Write(w.suffix[:w.suffixOff]) 645 return buf.Bytes() 646 } 647 648 func minInt(a, b int) int { 649 if a < b { 650 return a 651 } 652 return b 653 }