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