Source file src/os/exec/exec.go
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 // 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. 17 // 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. 21 // 22 // # Executables in the current directory 23 // 24 // The functions Command and LookPath look for a program 25 // in the directories listed in the current path, following the 26 // conventions of the host operating system. 27 // Operating systems have for decades included the current 28 // directory in this search, sometimes implicitly and sometimes 29 // configured explicitly that way by default. 30 // Modern practice is that including the current directory 31 // is usually unexpected and often leads to security problems. 32 // 33 // To avoid those security problems, as of Go 1.19, this package will not resolve a program 34 // using an implicit or explicit path entry relative to the current directory. 35 // That is, if you run exec.LookPath("go"), it will not successfully return 36 // ./go on Unix nor .\go.exe on Windows, no matter how the path is configured. 37 // Instead, if the usual path algorithms would result in that answer, 38 // these functions return an error err satisfying errors.Is(err, ErrDot). 39 // 40 // For example, consider these two program snippets: 41 // 42 // path, err := exec.LookPath("prog") 43 // if err != nil { 44 // log.Fatal(err) 45 // } 46 // use(path) 47 // 48 // and 49 // 50 // cmd := exec.Command("prog") 51 // if err := cmd.Run(); err != nil { 52 // log.Fatal(err) 53 // } 54 // 55 // These will not find and run ./prog or .\prog.exe, 56 // no matter how the current path is configured. 57 // 58 // Code that always wants to run a program from the current directory 59 // can be rewritten to say "./prog" instead of "prog". 60 // 61 // Code that insists on including results from relative path entries 62 // can instead override the error using an errors.Is check: 63 // 64 // path, err := exec.LookPath("prog") 65 // if errors.Is(err, exec.ErrDot) { 66 // err = nil 67 // } 68 // if err != nil { 69 // log.Fatal(err) 70 // } 71 // use(path) 72 // 73 // and 74 // 75 // cmd := exec.Command("prog") 76 // if errors.Is(cmd.Err, exec.ErrDot) { 77 // cmd.Err = nil 78 // } 79 // if err := cmd.Run(); err != nil { 80 // log.Fatal(err) 81 // } 82 // 83 // Setting the environment variable GODEBUG=execerrdot=0 84 // disables generation of ErrDot entirely, temporarily restoring the pre-Go 1.19 85 // behavior for programs that are unable to apply more targeted fixes. 86 // A future version of Go may remove support for this variable. 87 // 88 // Before adding such overrides, make sure you understand the 89 // security implications of doing so. 90 // See https://go.dev/blog/path-security for more information. 91 package exec 92 93 import ( 94 "bytes" 95 "context" 96 "errors" 97 "internal/godebug" 98 "internal/syscall/execenv" 99 "io" 100 "os" 101 "path/filepath" 102 "runtime" 103 "strconv" 104 "strings" 105 "syscall" 106 "time" 107 ) 108 109 // Error is returned by LookPath when it fails to classify a file as an 110 // executable. 111 type Error struct { 112 // Name is the file name for which the error occurred. 113 Name string 114 // Err is the underlying error. 115 Err error 116 } 117 118 func (e *Error) Error() string { 119 return "exec: " + strconv.Quote(e.Name) + ": " + e.Err.Error() 120 } 121 122 func (e *Error) Unwrap() error { return e.Err } 123 124 // ErrWaitDelay is returned by (*Cmd).Wait if the process exits with a 125 // successful status code but its output pipes are not closed before the 126 // command's WaitDelay expires. 127 var ErrWaitDelay = errors.New("exec: WaitDelay expired before I/O complete") 128 129 // wrappedError wraps an error without relying on fmt.Errorf. 130 type wrappedError struct { 131 prefix string 132 err error 133 } 134 135 func (w wrappedError) Error() string { 136 return w.prefix + ": " + w.err.Error() 137 } 138 139 func (w wrappedError) Unwrap() error { 140 return w.err 141 } 142 143 // Cmd represents an external command being prepared or run. 144 // 145 // A Cmd cannot be reused after calling its Run, Output or CombinedOutput 146 // methods. 147 type Cmd struct { 148 // Path is the path of the command to run. 149 // 150 // This is the only field that must be set to a non-zero 151 // value. If Path is relative, it is evaluated relative 152 // to Dir. 153 Path string 154 155 // Args holds command line arguments, including the command as Args[0]. 156 // If the Args field is empty or nil, Run uses {Path}. 157 // 158 // In typical use, both Path and Args are set by calling Command. 159 Args []string 160 161 // Env specifies the environment of the process. 162 // Each entry is of the form "key=value". 163 // If Env is nil, the new process uses the current process's 164 // environment. 165 // If Env contains duplicate environment keys, only the last 166 // value in the slice for each duplicate key is used. 167 // As a special case on Windows, SYSTEMROOT is always added if 168 // missing and not explicitly set to the empty string. 169 Env []string 170 171 // Dir specifies the working directory of the command. 172 // If Dir is the empty string, Run runs the command in the 173 // calling process's current directory. 174 Dir string 175 176 // Stdin specifies the process's standard input. 177 // 178 // If Stdin is nil, the process reads from the null device (os.DevNull). 179 // 180 // If Stdin is an *os.File, the process's standard input is connected 181 // directly to that file. 182 // 183 // Otherwise, during the execution of the command a separate 184 // goroutine reads from Stdin and delivers that data to the command 185 // over a pipe. In this case, Wait does not complete until the goroutine 186 // stops copying, either because it has reached the end of Stdin 187 // (EOF or a read error), or because writing to the pipe returned an error, 188 // or because a nonzero WaitDelay was set and expired. 189 Stdin io.Reader 190 191 // Stdout and Stderr specify the process's standard output and error. 192 // 193 // If either is nil, Run connects the corresponding file descriptor 194 // to the null device (os.DevNull). 195 // 196 // If either is an *os.File, the corresponding output from the process 197 // is connected directly to that file. 198 // 199 // Otherwise, during the execution of the command a separate goroutine 200 // reads from the process over a pipe and delivers that data to the 201 // corresponding Writer. In this case, Wait does not complete until the 202 // goroutine reaches EOF or encounters an error or a nonzero WaitDelay 203 // expires. 204 // 205 // If Stdout and Stderr are the same writer, and have a type that can 206 // be compared with ==, at most one goroutine at a time will call Write. 207 Stdout io.Writer 208 Stderr io.Writer 209 210 // ExtraFiles specifies additional open files to be inherited by the 211 // new process. It does not include standard input, standard output, or 212 // standard error. If non-nil, entry i becomes file descriptor 3+i. 213 // 214 // ExtraFiles is not supported on Windows. 215 ExtraFiles []*os.File 216 217 // SysProcAttr holds optional, operating system-specific attributes. 218 // Run passes it to os.StartProcess as the os.ProcAttr's Sys field. 219 SysProcAttr *syscall.SysProcAttr 220 221 // Process is the underlying process, once started. 222 Process *os.Process 223 224 // ProcessState contains information about an exited process. 225 // If the process was started successfully, Wait or Run will 226 // populate its ProcessState when the command completes. 227 ProcessState *os.ProcessState 228 229 // ctx is the context passed to CommandContext, if any. 230 ctx context.Context 231 232 Err error // LookPath error, if any. 233 234 // If Cancel is non-nil, the command must have been created with 235 // CommandContext and Cancel will be called when the command's 236 // Context is done. By default, CommandContext sets Cancel to 237 // call the Kill method on the command's Process. 238 // 239 // Typically a custom Cancel will send a signal to the command's 240 // Process, but it may instead take other actions to initiate cancellation, 241 // such as closing a stdin or stdout pipe or sending a shutdown request on a 242 // network socket. 243 // 244 // If the command exits with a success status after Cancel is 245 // called, and Cancel does not return an error equivalent to 246 // os.ErrProcessDone, then Wait and similar methods will return a non-nil 247 // error: either an error wrapping the one returned by Cancel, 248 // or the error from the Context. 249 // (If the command exits with a non-success status, or Cancel 250 // returns an error that wraps os.ErrProcessDone, Wait and similar methods 251 // continue to return the command's usual exit status.) 252 // 253 // If Cancel is set to nil, nothing will happen immediately when the command's 254 // Context is done, but a nonzero WaitDelay will still take effect. That may 255 // be useful, for example, to work around deadlocks in commands that do not 256 // support shutdown signals but are expected to always finish quickly. 257 // 258 // Cancel will not be called if Start returns a non-nil error. 259 Cancel func() error 260 261 // If WaitDelay is non-zero, it bounds the time spent waiting on two sources 262 // of unexpected delay in Wait: a child process that fails to exit after the 263 // associated Context is canceled, and a child process that exits but leaves 264 // its I/O pipes unclosed. 265 // 266 // The WaitDelay timer starts when either the associated Context is done or a 267 // call to Wait observes that the child process has exited, whichever occurs 268 // first. When the delay has elapsed, the command shuts down the child process 269 // and/or its I/O pipes. 270 // 271 // If the child process has failed to exit — perhaps because it ignored or 272 // failed to receive a shutdown signal from a Cancel function, or because no 273 // Cancel function was set — then it will be terminated using os.Process.Kill. 274 // 275 // Then, if the I/O pipes communicating with the child process are still open, 276 // those pipes are closed in order to unblock any goroutines currently blocked 277 // on Read or Write calls. 278 // 279 // If pipes are closed due to WaitDelay, no Cancel call has occurred, 280 // and the command has otherwise exited with a successful status, Wait and 281 // similar methods will return ErrWaitDelay instead of nil. 282 // 283 // If WaitDelay is zero (the default), I/O pipes will be read until EOF, 284 // which might not occur until orphaned subprocesses of the command have 285 // also closed their descriptors for the pipes. 286 WaitDelay time.Duration 287 288 // childIOFiles holds closers for any of the child process's 289 // stdin, stdout, and/or stderr files that were opened by the Cmd itself 290 // (not supplied by the caller). These should be closed as soon as they 291 // are inherited by the child process. 292 childIOFiles []io.Closer 293 294 // parentIOPipes holds closers for the parent's end of any pipes 295 // connected to the child's stdin, stdout, and/or stderr streams 296 // that were opened by the Cmd itself (not supplied by the caller). 297 // These should be closed after Wait sees the command and copying 298 // goroutines exit, or after WaitDelay has expired. 299 parentIOPipes []io.Closer 300 301 // goroutine holds a set of closures to execute to copy data 302 // to and/or from the command's I/O pipes. 303 goroutine []func() error 304 305 // If goroutineErr is non-nil, it receives the first error from a copying 306 // goroutine once all such goroutines have completed. 307 // goroutineErr is set to nil once its error has been received. 308 goroutineErr <-chan error 309 310 // If ctxResult is non-nil, it receives the result of watchCtx exactly once. 311 ctxResult <-chan ctxResult 312 313 // The stack saved when the Command was created, if GODEBUG contains 314 // execwait=2. Used for debugging leaks. 315 createdByStack []byte 316 317 // For a security release long ago, we created x/sys/execabs, 318 // which manipulated the unexported lookPathErr error field 319 // in this struct. For Go 1.19 we exported the field as Err error, 320 // above, but we have to keep lookPathErr around for use by 321 // old programs building against new toolchains. 322 // The String and Start methods look for an error in lookPathErr 323 // in preference to Err, to preserve the errors that execabs sets. 324 // 325 // In general we don't guarantee misuse of reflect like this, 326 // but the misuse of reflect was by us, the best of various bad 327 // options to fix the security problem, and people depend on 328 // those old copies of execabs continuing to work. 329 // The result is that we have to leave this variable around for the 330 // rest of time, a compatibility scar. 331 // 332 // See https://go.dev/blog/path-security 333 // and https://go.dev/issue/43724 for more context. 334 lookPathErr error 335 336 // cachedLookExtensions caches the result of calling lookExtensions. 337 // This is only used on Windows. 338 cachedLookExtensions string 339 } 340 341 // A ctxResult reports the result of watching the Context associated with a 342 // running command (and sending corresponding signals if needed). 343 type ctxResult struct { 344 err error 345 346 // If timer is non-nil, it expires after WaitDelay has elapsed after 347 // the Context is done. 348 // 349 // (If timer is nil, that means that the Context was not done before the 350 // command completed, or no WaitDelay was set, or the WaitDelay already 351 // expired and its effect was already applied.) 352 timer *time.Timer 353 } 354 355 var execwait = godebug.New("#execwait") 356 var execerrdot = godebug.New("execerrdot") 357 358 // Command returns the Cmd struct to execute the named program with 359 // the given arguments. 360 // 361 // It sets only the Path and Args in the returned structure. 362 // 363 // If name contains no path separators, Command uses LookPath to 364 // resolve name to a complete path if possible. Otherwise it uses name 365 // directly as Path. 366 // 367 // The returned Cmd's Args field is constructed from the command name 368 // followed by the elements of arg, so arg should not include the 369 // command name itself. For example, Command("echo", "hello"). 370 // Args[0] is always name, not the possibly resolved Path. 371 // 372 // On Windows, processes receive the whole command line as a single string 373 // and do their own parsing. Command combines and quotes Args into a command 374 // line string with an algorithm compatible with applications using 375 // CommandLineToArgvW (which is the most common way). Notable exceptions are 376 // msiexec.exe and cmd.exe (and thus, all batch files), which have a different 377 // unquoting algorithm. In these or other similar cases, you can do the 378 // quoting yourself and provide the full command line in SysProcAttr.CmdLine, 379 // leaving Args empty. 380 func Command(name string, arg ...string) *Cmd { 381 cmd := &Cmd{ 382 Path: name, 383 Args: append([]string{name}, arg...), 384 } 385 386 if v := execwait.Value(); v != "" { 387 if v == "2" { 388 // Obtain the caller stack. (This is equivalent to runtime/debug.Stack, 389 // copied to avoid importing the whole package.) 390 stack := make([]byte, 1024) 391 for { 392 n := runtime.Stack(stack, false) 393 if n < len(stack) { 394 stack = stack[:n] 395 break 396 } 397 stack = make([]byte, 2*len(stack)) 398 } 399 400 if i := bytes.Index(stack, []byte("\nos/exec.Command(")); i >= 0 { 401 stack = stack[i+1:] 402 } 403 cmd.createdByStack = stack 404 } 405 406 runtime.SetFinalizer(cmd, func(c *Cmd) { 407 if c.Process != nil && c.ProcessState == nil { 408 debugHint := "" 409 if c.createdByStack == nil { 410 debugHint = " (set GODEBUG=execwait=2 to capture stacks for debugging)" 411 } else { 412 os.Stderr.WriteString("GODEBUG=execwait=2 detected a leaked exec.Cmd created by:\n") 413 os.Stderr.Write(c.createdByStack) 414 os.Stderr.WriteString("\n") 415 debugHint = "" 416 } 417 panic("exec: Cmd started a Process but leaked without a call to Wait" + debugHint) 418 } 419 }) 420 } 421 422 if filepath.Base(name) == name { 423 lp, err := LookPath(name) 424 if lp != "" { 425 // Update cmd.Path even if err is non-nil. 426 // If err is ErrDot (especially on Windows), lp may include a resolved 427 // extension (like .exe or .bat) that should be preserved. 428 cmd.Path = lp 429 } 430 if err != nil { 431 cmd.Err = err 432 } 433 } else if runtime.GOOS == "windows" && filepath.IsAbs(name) { 434 // We may need to add a filename extension from PATHEXT 435 // or verify an extension that is already present. 436 // Since the path is absolute, its extension should be unambiguous 437 // and independent of cmd.Dir, and we can go ahead and cache the lookup now. 438 // 439 // Note that we cannot add an extension here for relative paths, because 440 // cmd.Dir may be set after we return from this function and that may cause 441 // the command to resolve to a different extension. 442 lp, err := lookExtensions(name, "") 443 cmd.cachedLookExtensions = lp 444 if err != nil { 445 cmd.Err = err 446 } 447 } 448 return cmd 449 } 450 451 // CommandContext is like Command but includes a context. 452 // 453 // The provided context is used to interrupt the process 454 // (by calling cmd.Cancel or os.Process.Kill) 455 // if the context becomes done before the command completes on its own. 456 // 457 // CommandContext sets the command's Cancel function to invoke the Kill method 458 // on its Process, and leaves its WaitDelay unset. The caller may change the 459 // cancellation behavior by modifying those fields before starting the command. 460 func CommandContext(ctx context.Context, name string, arg ...string) *Cmd { 461 if ctx == nil { 462 panic("nil Context") 463 } 464 cmd := Command(name, arg...) 465 cmd.ctx = ctx 466 cmd.Cancel = func() error { 467 return cmd.Process.Kill() 468 } 469 return cmd 470 } 471 472 // String returns a human-readable description of c. 473 // It is intended only for debugging. 474 // In particular, it is not suitable for use as input to a shell. 475 // The output of String may vary across Go releases. 476 func (c *Cmd) String() string { 477 if c.Err != nil || c.lookPathErr != nil { 478 // failed to resolve path; report the original requested path (plus args) 479 return strings.Join(c.Args, " ") 480 } 481 // report the exact executable path (plus args) 482 b := new(strings.Builder) 483 b.WriteString(c.Path) 484 for _, a := range c.Args[1:] { 485 b.WriteByte(' ') 486 b.WriteString(a) 487 } 488 return b.String() 489 } 490 491 // interfaceEqual protects against panics from doing equality tests on 492 // two interfaces with non-comparable underlying types. 493 func interfaceEqual(a, b any) bool { 494 defer func() { 495 recover() 496 }() 497 return a == b 498 } 499 500 func (c *Cmd) argv() []string { 501 if len(c.Args) > 0 { 502 return c.Args 503 } 504 return []string{c.Path} 505 } 506 507 func (c *Cmd) childStdin() (*os.File, error) { 508 if c.Stdin == nil { 509 f, err := os.Open(os.DevNull) 510 if err != nil { 511 return nil, err 512 } 513 c.childIOFiles = append(c.childIOFiles, f) 514 return f, nil 515 } 516 517 if f, ok := c.Stdin.(*os.File); ok { 518 return f, nil 519 } 520 521 pr, pw, err := os.Pipe() 522 if err != nil { 523 return nil, err 524 } 525 526 c.childIOFiles = append(c.childIOFiles, pr) 527 c.parentIOPipes = append(c.parentIOPipes, pw) 528 c.goroutine = append(c.goroutine, func() error { 529 _, err := io.Copy(pw, c.Stdin) 530 if skipStdinCopyError(err) { 531 err = nil 532 } 533 if err1 := pw.Close(); err == nil { 534 err = err1 535 } 536 return err 537 }) 538 return pr, nil 539 } 540 541 func (c *Cmd) childStdout() (*os.File, error) { 542 return c.writerDescriptor(c.Stdout) 543 } 544 545 func (c *Cmd) childStderr(childStdout *os.File) (*os.File, error) { 546 if c.Stderr != nil && interfaceEqual(c.Stderr, c.Stdout) { 547 return childStdout, nil 548 } 549 return c.writerDescriptor(c.Stderr) 550 } 551 552 // writerDescriptor returns an os.File to which the child process 553 // can write to send data to w. 554 // 555 // If w is nil, writerDescriptor returns a File that writes to os.DevNull. 556 func (c *Cmd) writerDescriptor(w io.Writer) (*os.File, error) { 557 if w == nil { 558 f, err := os.OpenFile(os.DevNull, os.O_WRONLY, 0) 559 if err != nil { 560 return nil, err 561 } 562 c.childIOFiles = append(c.childIOFiles, f) 563 return f, nil 564 } 565 566 if f, ok := w.(*os.File); ok { 567 return f, nil 568 } 569 570 pr, pw, err := os.Pipe() 571 if err != nil { 572 return nil, err 573 } 574 575 c.childIOFiles = append(c.childIOFiles, pw) 576 c.parentIOPipes = append(c.parentIOPipes, pr) 577 c.goroutine = append(c.goroutine, func() error { 578 _, err := io.Copy(w, pr) 579 pr.Close() // in case io.Copy stopped due to write error 580 return err 581 }) 582 return pw, nil 583 } 584 585 func closeDescriptors(closers []io.Closer) { 586 for _, fd := range closers { 587 fd.Close() 588 } 589 } 590 591 // Run starts the specified command and waits for it to complete. 592 // 593 // The returned error is nil if the command runs, has no problems 594 // copying stdin, stdout, and stderr, and exits with a zero exit 595 // status. 596 // 597 // If the command starts but does not complete successfully, the error is of 598 // type *ExitError. Other error types may be returned for other situations. 599 // 600 // If the calling goroutine has locked the operating system thread 601 // with runtime.LockOSThread and modified any inheritable OS-level 602 // thread state (for example, Linux or Plan 9 name spaces), the new 603 // process will inherit the caller's thread state. 604 func (c *Cmd) Run() error { 605 if err := c.Start(); err != nil { 606 return err 607 } 608 return c.Wait() 609 } 610 611 // Start starts the specified command but does not wait for it to complete. 612 // 613 // If Start returns successfully, the c.Process field will be set. 614 // 615 // After a successful call to Start the Wait method must be called in 616 // order to release associated system resources. 617 func (c *Cmd) Start() error { 618 // Check for doubled Start calls before we defer failure cleanup. If the prior 619 // call to Start succeeded, we don't want to spuriously close its pipes. 620 if c.Process != nil { 621 return errors.New("exec: already started") 622 } 623 624 started := false 625 defer func() { 626 closeDescriptors(c.childIOFiles) 627 c.childIOFiles = nil 628 629 if !started { 630 closeDescriptors(c.parentIOPipes) 631 c.parentIOPipes = nil 632 } 633 }() 634 635 if c.Path == "" && c.Err == nil && c.lookPathErr == nil { 636 c.Err = errors.New("exec: no command") 637 } 638 if c.Err != nil || c.lookPathErr != nil { 639 if c.lookPathErr != nil { 640 return c.lookPathErr 641 } 642 return c.Err 643 } 644 lp := c.Path 645 if c.cachedLookExtensions != "" { 646 lp = c.cachedLookExtensions 647 } 648 if runtime.GOOS == "windows" && c.cachedLookExtensions == "" { 649 // If c.Path is relative, we had to wait until now 650 // to resolve it in case c.Dir was changed. 651 // (If it is absolute, we already resolved its extension in Command 652 // and shouldn't need to do so again.) 653 // 654 // Unfortunately, we cannot write the result back to c.Path because programs 655 // may assume that they can call Start concurrently with reading the path. 656 // (It is safe and non-racy to do so on Unix platforms, and users might not 657 // test with the race detector on all platforms; 658 // see https://go.dev/issue/62596.) 659 // 660 // So we will pass the fully resolved path to os.StartProcess, but leave 661 // c.Path as is: missing a bit of logging information seems less harmful 662 // than triggering a surprising data race, and if the user really cares 663 // about that bit of logging they can always use LookPath to resolve it. 664 var err error 665 lp, err = lookExtensions(c.Path, c.Dir) 666 if err != nil { 667 return err 668 } 669 } 670 if c.Cancel != nil && c.ctx == nil { 671 return errors.New("exec: command with a non-nil Cancel was not created with CommandContext") 672 } 673 if c.ctx != nil { 674 select { 675 case <-c.ctx.Done(): 676 return c.ctx.Err() 677 default: 678 } 679 } 680 681 childFiles := make([]*os.File, 0, 3+len(c.ExtraFiles)) 682 stdin, err := c.childStdin() 683 if err != nil { 684 return err 685 } 686 childFiles = append(childFiles, stdin) 687 stdout, err := c.childStdout() 688 if err != nil { 689 return err 690 } 691 childFiles = append(childFiles, stdout) 692 stderr, err := c.childStderr(stdout) 693 if err != nil { 694 return err 695 } 696 childFiles = append(childFiles, stderr) 697 childFiles = append(childFiles, c.ExtraFiles...) 698 699 env, err := c.environ() 700 if err != nil { 701 return err 702 } 703 704 c.Process, err = os.StartProcess(lp, c.argv(), &os.ProcAttr{ 705 Dir: c.Dir, 706 Files: childFiles, 707 Env: env, 708 Sys: c.SysProcAttr, 709 }) 710 if err != nil { 711 return err 712 } 713 started = true 714 715 // Don't allocate the goroutineErr channel unless there are goroutines to start. 716 if len(c.goroutine) > 0 { 717 goroutineErr := make(chan error, 1) 718 c.goroutineErr = goroutineErr 719 720 type goroutineStatus struct { 721 running int 722 firstErr error 723 } 724 statusc := make(chan goroutineStatus, 1) 725 statusc <- goroutineStatus{running: len(c.goroutine)} 726 for _, fn := range c.goroutine { 727 go func(fn func() error) { 728 err := fn() 729 730 status := <-statusc 731 if status.firstErr == nil { 732 status.firstErr = err 733 } 734 status.running-- 735 if status.running == 0 { 736 goroutineErr <- status.firstErr 737 } else { 738 statusc <- status 739 } 740 }(fn) 741 } 742 c.goroutine = nil // Allow the goroutines' closures to be GC'd when they complete. 743 } 744 745 // If we have anything to do when the command's Context expires, 746 // start a goroutine to watch for cancellation. 747 // 748 // (Even if the command was created by CommandContext, a helper library may 749 // have explicitly set its Cancel field back to nil, indicating that it should 750 // be allowed to continue running after cancellation after all.) 751 if (c.Cancel != nil || c.WaitDelay != 0) && c.ctx != nil && c.ctx.Done() != nil { 752 resultc := make(chan ctxResult) 753 c.ctxResult = resultc 754 go c.watchCtx(resultc) 755 } 756 757 return nil 758 } 759 760 // watchCtx watches c.ctx until it is able to send a result to resultc. 761 // 762 // If c.ctx is done before a result can be sent, watchCtx calls c.Cancel, 763 // and/or kills cmd.Process it after c.WaitDelay has elapsed. 764 // 765 // watchCtx manipulates c.goroutineErr, so its result must be received before 766 // c.awaitGoroutines is called. 767 func (c *Cmd) watchCtx(resultc chan<- ctxResult) { 768 select { 769 case resultc <- ctxResult{}: 770 return 771 case <-c.ctx.Done(): 772 } 773 774 var err error 775 if c.Cancel != nil { 776 if interruptErr := c.Cancel(); interruptErr == nil { 777 // We appear to have successfully interrupted the command, so any 778 // program behavior from this point may be due to ctx even if the 779 // command exits with code 0. 780 err = c.ctx.Err() 781 } else if errors.Is(interruptErr, os.ErrProcessDone) { 782 // The process already finished: we just didn't notice it yet. 783 // (Perhaps c.Wait hadn't been called, or perhaps it happened to race with 784 // c.ctx being cancelled.) Don't inject a needless error. 785 } else { 786 err = wrappedError{ 787 prefix: "exec: canceling Cmd", 788 err: interruptErr, 789 } 790 } 791 } 792 if c.WaitDelay == 0 { 793 resultc <- ctxResult{err: err} 794 return 795 } 796 797 timer := time.NewTimer(c.WaitDelay) 798 select { 799 case resultc <- ctxResult{err: err, timer: timer}: 800 // c.Process.Wait returned and we've handed the timer off to c.Wait. 801 // It will take care of goroutine shutdown from here. 802 return 803 case <-timer.C: 804 } 805 806 killed := false 807 if killErr := c.Process.Kill(); killErr == nil { 808 // We appear to have killed the process. c.Process.Wait should return a 809 // non-nil error to c.Wait unless the Kill signal races with a successful 810 // exit, and if that does happen we shouldn't report a spurious error, 811 // so don't set err to anything here. 812 killed = true 813 } else if !errors.Is(killErr, os.ErrProcessDone) { 814 err = wrappedError{ 815 prefix: "exec: killing Cmd", 816 err: killErr, 817 } 818 } 819 820 if c.goroutineErr != nil { 821 select { 822 case goroutineErr := <-c.goroutineErr: 823 // Forward goroutineErr only if we don't have reason to believe it was 824 // caused by a call to Cancel or Kill above. 825 if err == nil && !killed { 826 err = goroutineErr 827 } 828 default: 829 // Close the child process's I/O pipes, in case it abandoned some 830 // subprocess that inherited them and is still holding them open 831 // (see https://go.dev/issue/23019). 832 // 833 // We close the goroutine pipes only after we have sent any signals we're 834 // going to send to the process (via Signal or Kill above): if we send 835 // SIGKILL to the process, we would prefer for it to die of SIGKILL, not 836 // SIGPIPE. (However, this may still cause any orphaned subprocesses to 837 // terminate with SIGPIPE.) 838 closeDescriptors(c.parentIOPipes) 839 // Wait for the copying goroutines to finish, but report ErrWaitDelay for 840 // the error: any other error here could result from closing the pipes. 841 _ = <-c.goroutineErr 842 if err == nil { 843 err = ErrWaitDelay 844 } 845 } 846 847 // Since we have already received the only result from c.goroutineErr, 848 // set it to nil to prevent awaitGoroutines from blocking on it. 849 c.goroutineErr = nil 850 } 851 852 resultc <- ctxResult{err: err} 853 } 854 855 // An ExitError reports an unsuccessful exit by a command. 856 type ExitError struct { 857 *os.ProcessState 858 859 // Stderr holds a subset of the standard error output from the 860 // Cmd.Output method if standard error was not otherwise being 861 // collected. 862 // 863 // If the error output is long, Stderr may contain only a prefix 864 // and suffix of the output, with the middle replaced with 865 // text about the number of omitted bytes. 866 // 867 // Stderr is provided for debugging, for inclusion in error messages. 868 // Users with other needs should redirect Cmd.Stderr as needed. 869 Stderr []byte 870 } 871 872 func (e *ExitError) Error() string { 873 return e.ProcessState.String() 874 } 875 876 // Wait waits for the command to exit and waits for any copying to 877 // stdin or copying from stdout or stderr to complete. 878 // 879 // The command must have been started by Start. 880 // 881 // The returned error is nil if the command runs, has no problems 882 // copying stdin, stdout, and stderr, and exits with a zero exit 883 // status. 884 // 885 // If the command fails to run or doesn't complete successfully, the 886 // error is of type *ExitError. Other error types may be 887 // returned for I/O problems. 888 // 889 // If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits 890 // for the respective I/O loop copying to or from the process to complete. 891 // 892 // Wait releases any resources associated with the Cmd. 893 func (c *Cmd) Wait() error { 894 if c.Process == nil { 895 return errors.New("exec: not started") 896 } 897 if c.ProcessState != nil { 898 return errors.New("exec: Wait was already called") 899 } 900 901 state, err := c.Process.Wait() 902 if err == nil && !state.Success() { 903 err = &ExitError{ProcessState: state} 904 } 905 c.ProcessState = state 906 907 var timer *time.Timer 908 if c.ctxResult != nil { 909 watch := <-c.ctxResult 910 timer = watch.timer 911 // If c.Process.Wait returned an error, prefer that. 912 // Otherwise, report any error from the watchCtx goroutine, 913 // such as a Context cancellation or a WaitDelay overrun. 914 if err == nil && watch.err != nil { 915 err = watch.err 916 } 917 } 918 919 if goroutineErr := c.awaitGoroutines(timer); err == nil { 920 // Report an error from the copying goroutines only if the program otherwise 921 // exited normally on its own. Otherwise, the copying error may be due to the 922 // abnormal termination. 923 err = goroutineErr 924 } 925 closeDescriptors(c.parentIOPipes) 926 c.parentIOPipes = nil 927 928 return err 929 } 930 931 // awaitGoroutines waits for the results of the goroutines copying data to or 932 // from the command's I/O pipes. 933 // 934 // If c.WaitDelay elapses before the goroutines complete, awaitGoroutines 935 // forcibly closes their pipes and returns ErrWaitDelay. 936 // 937 // If timer is non-nil, it must send to timer.C at the end of c.WaitDelay. 938 func (c *Cmd) awaitGoroutines(timer *time.Timer) error { 939 defer func() { 940 if timer != nil { 941 timer.Stop() 942 } 943 c.goroutineErr = nil 944 }() 945 946 if c.goroutineErr == nil { 947 return nil // No running goroutines to await. 948 } 949 950 if timer == nil { 951 if c.WaitDelay == 0 { 952 return <-c.goroutineErr 953 } 954 955 select { 956 case err := <-c.goroutineErr: 957 // Avoid the overhead of starting a timer. 958 return err 959 default: 960 } 961 962 // No existing timer was started: either there is no Context associated with 963 // the command, or c.Process.Wait completed before the Context was done. 964 timer = time.NewTimer(c.WaitDelay) 965 } 966 967 select { 968 case <-timer.C: 969 closeDescriptors(c.parentIOPipes) 970 // Wait for the copying goroutines to finish, but ignore any error 971 // (since it was probably caused by closing the pipes). 972 _ = <-c.goroutineErr 973 return ErrWaitDelay 974 975 case err := <-c.goroutineErr: 976 return err 977 } 978 } 979 980 // Output runs the command and returns its standard output. 981 // Any returned error will usually be of type *ExitError. 982 // If c.Stderr was nil, Output populates ExitError.Stderr. 983 func (c *Cmd) Output() ([]byte, error) { 984 if c.Stdout != nil { 985 return nil, errors.New("exec: Stdout already set") 986 } 987 var stdout bytes.Buffer 988 c.Stdout = &stdout 989 990 captureErr := c.Stderr == nil 991 if captureErr { 992 c.Stderr = &prefixSuffixSaver{N: 32 << 10} 993 } 994 995 err := c.Run() 996 if err != nil && captureErr { 997 if ee, ok := err.(*ExitError); ok { 998 ee.Stderr = c.Stderr.(*prefixSuffixSaver).Bytes() 999 } 1000 } 1001 return stdout.Bytes(), err 1002 } 1003 1004 // CombinedOutput runs the command and returns its combined standard 1005 // output and standard error. 1006 func (c *Cmd) CombinedOutput() ([]byte, error) { 1007 if c.Stdout != nil { 1008 return nil, errors.New("exec: Stdout already set") 1009 } 1010 if c.Stderr != nil { 1011 return nil, errors.New("exec: Stderr already set") 1012 } 1013 var b bytes.Buffer 1014 c.Stdout = &b 1015 c.Stderr = &b 1016 err := c.Run() 1017 return b.Bytes(), err 1018 } 1019 1020 // StdinPipe returns a pipe that will be connected to the command's 1021 // standard input when the command starts. 1022 // The pipe will be closed automatically after Wait sees the command exit. 1023 // A caller need only call Close to force the pipe to close sooner. 1024 // For example, if the command being run will not exit until standard input 1025 // is closed, the caller must close the pipe. 1026 func (c *Cmd) StdinPipe() (io.WriteCloser, error) { 1027 if c.Stdin != nil { 1028 return nil, errors.New("exec: Stdin already set") 1029 } 1030 if c.Process != nil { 1031 return nil, errors.New("exec: StdinPipe after process started") 1032 } 1033 pr, pw, err := os.Pipe() 1034 if err != nil { 1035 return nil, err 1036 } 1037 c.Stdin = pr 1038 c.childIOFiles = append(c.childIOFiles, pr) 1039 c.parentIOPipes = append(c.parentIOPipes, pw) 1040 return pw, nil 1041 } 1042 1043 // StdoutPipe returns a pipe that will be connected to the command's 1044 // standard output when the command starts. 1045 // 1046 // Wait will close the pipe after seeing the command exit, so most callers 1047 // need not close the pipe themselves. It is thus incorrect to call Wait 1048 // before all reads from the pipe have completed. 1049 // For the same reason, it is incorrect to call Run when using StdoutPipe. 1050 // See the example for idiomatic usage. 1051 func (c *Cmd) StdoutPipe() (io.ReadCloser, error) { 1052 if c.Stdout != nil { 1053 return nil, errors.New("exec: Stdout already set") 1054 } 1055 if c.Process != nil { 1056 return nil, errors.New("exec: StdoutPipe after process started") 1057 } 1058 pr, pw, err := os.Pipe() 1059 if err != nil { 1060 return nil, err 1061 } 1062 c.Stdout = pw 1063 c.childIOFiles = append(c.childIOFiles, pw) 1064 c.parentIOPipes = append(c.parentIOPipes, pr) 1065 return pr, nil 1066 } 1067 1068 // StderrPipe returns a pipe that will be connected to the command's 1069 // standard error when the command starts. 1070 // 1071 // Wait will close the pipe after seeing the command exit, so most callers 1072 // need not close the pipe themselves. It is thus incorrect to call Wait 1073 // before all reads from the pipe have completed. 1074 // For the same reason, it is incorrect to use Run when using StderrPipe. 1075 // See the StdoutPipe example for idiomatic usage. 1076 func (c *Cmd) StderrPipe() (io.ReadCloser, error) { 1077 if c.Stderr != nil { 1078 return nil, errors.New("exec: Stderr already set") 1079 } 1080 if c.Process != nil { 1081 return nil, errors.New("exec: StderrPipe after process started") 1082 } 1083 pr, pw, err := os.Pipe() 1084 if err != nil { 1085 return nil, err 1086 } 1087 c.Stderr = pw 1088 c.childIOFiles = append(c.childIOFiles, pw) 1089 c.parentIOPipes = append(c.parentIOPipes, pr) 1090 return pr, nil 1091 } 1092 1093 // prefixSuffixSaver is an io.Writer which retains the first N bytes 1094 // and the last N bytes written to it. The Bytes() methods reconstructs 1095 // it with a pretty error message. 1096 type prefixSuffixSaver struct { 1097 N int // max size of prefix or suffix 1098 prefix []byte 1099 suffix []byte // ring buffer once len(suffix) == N 1100 suffixOff int // offset to write into suffix 1101 skipped int64 1102 1103 // TODO(bradfitz): we could keep one large []byte and use part of it for 1104 // the prefix, reserve space for the '... Omitting N bytes ...' message, 1105 // then the ring buffer suffix, and just rearrange the ring buffer 1106 // suffix when Bytes() is called, but it doesn't seem worth it for 1107 // now just for error messages. It's only ~64KB anyway. 1108 } 1109 1110 func (w *prefixSuffixSaver) Write(p []byte) (n int, err error) { 1111 lenp := len(p) 1112 p = w.fill(&w.prefix, p) 1113 1114 // Only keep the last w.N bytes of suffix data. 1115 if overage := len(p) - w.N; overage > 0 { 1116 p = p[overage:] 1117 w.skipped += int64(overage) 1118 } 1119 p = w.fill(&w.suffix, p) 1120 1121 // w.suffix is full now if p is non-empty. Overwrite it in a circle. 1122 for len(p) > 0 { // 0, 1, or 2 iterations. 1123 n := copy(w.suffix[w.suffixOff:], p) 1124 p = p[n:] 1125 w.skipped += int64(n) 1126 w.suffixOff += n 1127 if w.suffixOff == w.N { 1128 w.suffixOff = 0 1129 } 1130 } 1131 return lenp, nil 1132 } 1133 1134 // fill appends up to len(p) bytes of p to *dst, such that *dst does not 1135 // grow larger than w.N. It returns the un-appended suffix of p. 1136 func (w *prefixSuffixSaver) fill(dst *[]byte, p []byte) (pRemain []byte) { 1137 if remain := w.N - len(*dst); remain > 0 { 1138 add := min(len(p), remain) 1139 *dst = append(*dst, p[:add]...) 1140 p = p[add:] 1141 } 1142 return p 1143 } 1144 1145 func (w *prefixSuffixSaver) Bytes() []byte { 1146 if w.suffix == nil { 1147 return w.prefix 1148 } 1149 if w.skipped == 0 { 1150 return append(w.prefix, w.suffix...) 1151 } 1152 var buf bytes.Buffer 1153 buf.Grow(len(w.prefix) + len(w.suffix) + 50) 1154 buf.Write(w.prefix) 1155 buf.WriteString("\n... omitting ") 1156 buf.WriteString(strconv.FormatInt(w.skipped, 10)) 1157 buf.WriteString(" bytes ...\n") 1158 buf.Write(w.suffix[w.suffixOff:]) 1159 buf.Write(w.suffix[:w.suffixOff]) 1160 return buf.Bytes() 1161 } 1162 1163 // environ returns a best-effort copy of the environment in which the command 1164 // would be run as it is currently configured. If an error occurs in computing 1165 // the environment, it is returned alongside the best-effort copy. 1166 func (c *Cmd) environ() ([]string, error) { 1167 var err error 1168 1169 env := c.Env 1170 if env == nil { 1171 env, err = execenv.Default(c.SysProcAttr) 1172 if err != nil { 1173 env = os.Environ() 1174 // Note that the non-nil err is preserved despite env being overridden. 1175 } 1176 1177 if c.Dir != "" { 1178 switch runtime.GOOS { 1179 case "windows", "plan9": 1180 // Windows and Plan 9 do not use the PWD variable, so we don't need to 1181 // keep it accurate. 1182 default: 1183 // On POSIX platforms, PWD represents “an absolute pathname of the 1184 // current working directory.” Since we are changing the working 1185 // directory for the command, we should also update PWD to reflect that. 1186 // 1187 // Unfortunately, we didn't always do that, so (as proposed in 1188 // https://go.dev/issue/50599) to avoid unintended collateral damage we 1189 // only implicitly update PWD when Env is nil. That way, we're much 1190 // less likely to override an intentional change to the variable. 1191 if pwd, absErr := filepath.Abs(c.Dir); absErr == nil { 1192 env = append(env, "PWD="+pwd) 1193 } else if err == nil { 1194 err = absErr 1195 } 1196 } 1197 } 1198 } 1199 1200 env, dedupErr := dedupEnv(env) 1201 if err == nil { 1202 err = dedupErr 1203 } 1204 return addCriticalEnv(env), err 1205 } 1206 1207 // Environ returns a copy of the environment in which the command would be run 1208 // as it is currently configured. 1209 func (c *Cmd) Environ() []string { 1210 // Intentionally ignore errors: environ returns a best-effort environment no matter what. 1211 env, _ := c.environ() 1212 return env 1213 } 1214 1215 // dedupEnv returns a copy of env with any duplicates removed, in favor of 1216 // later values. 1217 // Items not of the normal environment "key=value" form are preserved unchanged. 1218 // Except on Plan 9, items containing NUL characters are removed, and 1219 // an error is returned along with the remaining values. 1220 func dedupEnv(env []string) ([]string, error) { 1221 return dedupEnvCase(runtime.GOOS == "windows", runtime.GOOS == "plan9", env) 1222 } 1223 1224 // dedupEnvCase is dedupEnv with a case option for testing. 1225 // If caseInsensitive is true, the case of keys is ignored. 1226 // If nulOK is false, items containing NUL characters are allowed. 1227 func dedupEnvCase(caseInsensitive, nulOK bool, env []string) ([]string, error) { 1228 // Construct the output in reverse order, to preserve the 1229 // last occurrence of each key. 1230 var err error 1231 out := make([]string, 0, len(env)) 1232 saw := make(map[string]bool, len(env)) 1233 for n := len(env); n > 0; n-- { 1234 kv := env[n-1] 1235 1236 // Reject NUL in environment variables to prevent security issues (#56284); 1237 // except on Plan 9, which uses NUL as os.PathListSeparator (#56544). 1238 if !nulOK && strings.IndexByte(kv, 0) != -1 { 1239 err = errors.New("exec: environment variable contains NUL") 1240 continue 1241 } 1242 1243 i := strings.Index(kv, "=") 1244 if i == 0 { 1245 // We observe in practice keys with a single leading "=" on Windows. 1246 // TODO(#49886): Should we consume only the first leading "=" as part 1247 // of the key, or parse through arbitrarily many of them until a non-"="? 1248 i = strings.Index(kv[1:], "=") + 1 1249 } 1250 if i < 0 { 1251 if kv != "" { 1252 // The entry is not of the form "key=value" (as it is required to be). 1253 // Leave it as-is for now. 1254 // TODO(#52436): should we strip or reject these bogus entries? 1255 out = append(out, kv) 1256 } 1257 continue 1258 } 1259 k := kv[:i] 1260 if caseInsensitive { 1261 k = strings.ToLower(k) 1262 } 1263 if saw[k] { 1264 continue 1265 } 1266 1267 saw[k] = true 1268 out = append(out, kv) 1269 } 1270 1271 // Now reverse the slice to restore the original order. 1272 for i := 0; i < len(out)/2; i++ { 1273 j := len(out) - i - 1 1274 out[i], out[j] = out[j], out[i] 1275 } 1276 1277 return out, err 1278 } 1279 1280 // addCriticalEnv adds any critical environment variables that are required 1281 // (or at least almost always required) on the operating system. 1282 // Currently this is only used for Windows. 1283 func addCriticalEnv(env []string) []string { 1284 if runtime.GOOS != "windows" { 1285 return env 1286 } 1287 for _, kv := range env { 1288 k, _, ok := strings.Cut(kv, "=") 1289 if !ok { 1290 continue 1291 } 1292 if strings.EqualFold(k, "SYSTEMROOT") { 1293 // We already have it. 1294 return env 1295 } 1296 } 1297 return append(env, "SYSTEMROOT="+os.Getenv("SYSTEMROOT")) 1298 } 1299 1300 // ErrDot indicates that a path lookup resolved to an executable 1301 // in the current directory due to ‘.’ being in the path, either 1302 // implicitly or explicitly. See the package documentation for details. 1303 // 1304 // Note that functions in this package do not return ErrDot directly. 1305 // Code should use errors.Is(err, ErrDot), not err == ErrDot, 1306 // to test whether a returned error err is due to this condition. 1307 var ErrDot = errors.New("cannot run executable found relative to current directory") 1308