exec.go

Documentation: os/exec

		 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  package exec
		22  
		23  import (
		24  	"bytes"
		25  	"context"
		26  	"errors"
		27  	"internal/syscall/execenv"
		28  	"io"
		29  	"os"
		30  	"path/filepath"
		31  	"runtime"
		32  	"strconv"
		33  	"strings"
		34  	"sync"
		35  	"syscall"
		36  )
		37  
		38  // Error is returned by LookPath when it fails to classify a file as an
		39  // executable.
		40  type Error struct {
		41  	// Name is the file name for which the error occurred.
		42  	Name string
		43  	// Err is the underlying error.
		44  	Err error
		45  }
		46  
		47  func (e *Error) Error() string {
		48  	return "exec: " + strconv.Quote(e.Name) + ": " + e.Err.Error()
		49  }
		50  
		51  func (e *Error) Unwrap() error { return e.Err }
		52  
		53  // Cmd represents an external command being prepared or run.
		54  //
		55  // A Cmd cannot be reused after calling its Run, Output or CombinedOutput
		56  // methods.
		57  type Cmd struct {
		58  	// Path is the path of the command to run.
		59  	//
		60  	// This is the only field that must be set to a non-zero
		61  	// value. If Path is relative, it is evaluated relative
		62  	// to Dir.
		63  	Path string
		64  
		65  	// Args holds command line arguments, including the command as Args[0].
		66  	// If the Args field is empty or nil, Run uses {Path}.
		67  	//
		68  	// In typical use, both Path and Args are set by calling Command.
		69  	Args []string
		70  
		71  	// Env specifies the environment of the process.
		72  	// Each entry is of the form "key=value".
		73  	// If Env is nil, the new process uses the current process's
		74  	// environment.
		75  	// If Env contains duplicate environment keys, only the last
		76  	// value in the slice for each duplicate key is used.
		77  	// As a special case on Windows, SYSTEMROOT is always added if
		78  	// missing and not explicitly set to the empty string.
		79  	Env []string
		80  
		81  	// Dir specifies the working directory of the command.
		82  	// If Dir is the empty string, Run runs the command in the
		83  	// calling process's current directory.
		84  	Dir string
		85  
		86  	// Stdin specifies the process's standard input.
		87  	//
		88  	// If Stdin is nil, the process reads from the null device (os.DevNull).
		89  	//
		90  	// If Stdin is an *os.File, the process's standard input is connected
		91  	// directly to that file.
		92  	//
		93  	// Otherwise, during the execution of the command a separate
		94  	// goroutine reads from Stdin and delivers that data to the command
		95  	// over a pipe. In this case, Wait does not complete until the goroutine
		96  	// stops copying, either because it has reached the end of Stdin
		97  	// (EOF or a read error) or because writing to the pipe returned an error.
		98  	Stdin io.Reader
		99  
	 100  	// Stdout and Stderr specify the process's standard output and error.
	 101  	//
	 102  	// If either is nil, Run connects the corresponding file descriptor
	 103  	// to the null device (os.DevNull).
	 104  	//
	 105  	// If either is an *os.File, the corresponding output from the process
	 106  	// is connected directly to that file.
	 107  	//
	 108  	// Otherwise, during the execution of the command a separate goroutine
	 109  	// reads from the process over a pipe and delivers that data to the
	 110  	// corresponding Writer. In this case, Wait does not complete until the
	 111  	// goroutine reaches EOF or encounters an error.
	 112  	//
	 113  	// If Stdout and Stderr are the same writer, and have a type that can
	 114  	// be compared with ==, at most one goroutine at a time will call Write.
	 115  	Stdout io.Writer
	 116  	Stderr io.Writer
	 117  
	 118  	// ExtraFiles specifies additional open files to be inherited by the
	 119  	// new process. It does not include standard input, standard output, or
	 120  	// standard error. If non-nil, entry i becomes file descriptor 3+i.
	 121  	//
	 122  	// ExtraFiles is not supported on Windows.
	 123  	ExtraFiles []*os.File
	 124  
	 125  	// SysProcAttr holds optional, operating system-specific attributes.
	 126  	// Run passes it to os.StartProcess as the os.ProcAttr's Sys field.
	 127  	SysProcAttr *syscall.SysProcAttr
	 128  
	 129  	// Process is the underlying process, once started.
	 130  	Process *os.Process
	 131  
	 132  	// ProcessState contains information about an exited process,
	 133  	// available after a call to Wait or Run.
	 134  	ProcessState *os.ProcessState
	 135  
	 136  	ctx						 context.Context // nil means none
	 137  	lookPathErr		 error					 // LookPath error, if any.
	 138  	finished				bool						// when Wait was called
	 139  	childFiles			[]*os.File
	 140  	closeAfterStart []io.Closer
	 141  	closeAfterWait	[]io.Closer
	 142  	goroutine			 []func() error
	 143  	errch					 chan error // one send per goroutine
	 144  	waitDone				chan struct{}
	 145  }
	 146  
	 147  // Command returns the Cmd struct to execute the named program with
	 148  // the given arguments.
	 149  //
	 150  // It sets only the Path and Args in the returned structure.
	 151  //
	 152  // If name contains no path separators, Command uses LookPath to
	 153  // resolve name to a complete path if possible. Otherwise it uses name
	 154  // directly as Path.
	 155  //
	 156  // The returned Cmd's Args field is constructed from the command name
	 157  // followed by the elements of arg, so arg should not include the
	 158  // command name itself. For example, Command("echo", "hello").
	 159  // Args[0] is always name, not the possibly resolved Path.
	 160  //
	 161  // On Windows, processes receive the whole command line as a single string
	 162  // and do their own parsing. Command combines and quotes Args into a command
	 163  // line string with an algorithm compatible with applications using
	 164  // CommandLineToArgvW (which is the most common way). Notable exceptions are
	 165  // msiexec.exe and cmd.exe (and thus, all batch files), which have a different
	 166  // unquoting algorithm. In these or other similar cases, you can do the
	 167  // quoting yourself and provide the full command line in SysProcAttr.CmdLine,
	 168  // leaving Args empty.
	 169  func Command(name string, arg ...string) *Cmd {
	 170  	cmd := &Cmd{
	 171  		Path: name,
	 172  		Args: append([]string{name}, arg...),
	 173  	}
	 174  	if filepath.Base(name) == name {
	 175  		if lp, err := LookPath(name); err != nil {
	 176  			cmd.lookPathErr = err
	 177  		} else {
	 178  			cmd.Path = lp
	 179  		}
	 180  	}
	 181  	return cmd
	 182  }
	 183  
	 184  // CommandContext is like Command but includes a context.
	 185  //
	 186  // The provided context is used to kill the process (by calling
	 187  // os.Process.Kill) if the context becomes done before the command
	 188  // completes on its own.
	 189  func CommandContext(ctx context.Context, name string, arg ...string) *Cmd {
	 190  	if ctx == nil {
	 191  		panic("nil Context")
	 192  	}
	 193  	cmd := Command(name, arg...)
	 194  	cmd.ctx = ctx
	 195  	return cmd
	 196  }
	 197  
	 198  // String returns a human-readable description of c.
	 199  // It is intended only for debugging.
	 200  // In particular, it is not suitable for use as input to a shell.
	 201  // The output of String may vary across Go releases.
	 202  func (c *Cmd) String() string {
	 203  	if c.lookPathErr != nil {
	 204  		// failed to resolve path; report the original requested path (plus args)
	 205  		return strings.Join(c.Args, " ")
	 206  	}
	 207  	// report the exact executable path (plus args)
	 208  	b := new(strings.Builder)
	 209  	b.WriteString(c.Path)
	 210  	for _, a := range c.Args[1:] {
	 211  		b.WriteByte(' ')
	 212  		b.WriteString(a)
	 213  	}
	 214  	return b.String()
	 215  }
	 216  
	 217  // interfaceEqual protects against panics from doing equality tests on
	 218  // two interfaces with non-comparable underlying types.
	 219  func interfaceEqual(a, b interface{}) bool {
	 220  	defer func() {
	 221  		recover()
	 222  	}()
	 223  	return a == b
	 224  }
	 225  
	 226  func (c *Cmd) envv() ([]string, error) {
	 227  	if c.Env != nil {
	 228  		return c.Env, nil
	 229  	}
	 230  	return execenv.Default(c.SysProcAttr)
	 231  }
	 232  
	 233  func (c *Cmd) argv() []string {
	 234  	if len(c.Args) > 0 {
	 235  		return c.Args
	 236  	}
	 237  	return []string{c.Path}
	 238  }
	 239  
	 240  // skipStdinCopyError optionally specifies a function which reports
	 241  // whether the provided stdin copy error should be ignored.
	 242  var skipStdinCopyError func(error) bool
	 243  
	 244  func (c *Cmd) stdin() (f *os.File, err error) {
	 245  	if c.Stdin == nil {
	 246  		f, err = os.Open(os.DevNull)
	 247  		if err != nil {
	 248  			return
	 249  		}
	 250  		c.closeAfterStart = append(c.closeAfterStart, f)
	 251  		return
	 252  	}
	 253  
	 254  	if f, ok := c.Stdin.(*os.File); ok {
	 255  		return f, nil
	 256  	}
	 257  
	 258  	pr, pw, err := os.Pipe()
	 259  	if err != nil {
	 260  		return
	 261  	}
	 262  
	 263  	c.closeAfterStart = append(c.closeAfterStart, pr)
	 264  	c.closeAfterWait = append(c.closeAfterWait, pw)
	 265  	c.goroutine = append(c.goroutine, func() error {
	 266  		_, err := io.Copy(pw, c.Stdin)
	 267  		if skip := skipStdinCopyError; skip != nil && skip(err) {
	 268  			err = nil
	 269  		}
	 270  		if err1 := pw.Close(); err == nil {
	 271  			err = err1
	 272  		}
	 273  		return err
	 274  	})
	 275  	return pr, nil
	 276  }
	 277  
	 278  func (c *Cmd) stdout() (f *os.File, err error) {
	 279  	return c.writerDescriptor(c.Stdout)
	 280  }
	 281  
	 282  func (c *Cmd) stderr() (f *os.File, err error) {
	 283  	if c.Stderr != nil && interfaceEqual(c.Stderr, c.Stdout) {
	 284  		return c.childFiles[1], nil
	 285  	}
	 286  	return c.writerDescriptor(c.Stderr)
	 287  }
	 288  
	 289  func (c *Cmd) writerDescriptor(w io.Writer) (f *os.File, err error) {
	 290  	if w == nil {
	 291  		f, err = os.OpenFile(os.DevNull, os.O_WRONLY, 0)
	 292  		if err != nil {
	 293  			return
	 294  		}
	 295  		c.closeAfterStart = append(c.closeAfterStart, f)
	 296  		return
	 297  	}
	 298  
	 299  	if f, ok := w.(*os.File); ok {
	 300  		return f, nil
	 301  	}
	 302  
	 303  	pr, pw, err := os.Pipe()
	 304  	if err != nil {
	 305  		return
	 306  	}
	 307  
	 308  	c.closeAfterStart = append(c.closeAfterStart, pw)
	 309  	c.closeAfterWait = append(c.closeAfterWait, pr)
	 310  	c.goroutine = append(c.goroutine, func() error {
	 311  		_, err := io.Copy(w, pr)
	 312  		pr.Close() // in case io.Copy stopped due to write error
	 313  		return err
	 314  	})
	 315  	return pw, nil
	 316  }
	 317  
	 318  func (c *Cmd) closeDescriptors(closers []io.Closer) {
	 319  	for _, fd := range closers {
	 320  		fd.Close()
	 321  	}
	 322  }
	 323  
	 324  // Run starts the specified command and waits for it to complete.
	 325  //
	 326  // The returned error is nil if the command runs, has no problems
	 327  // copying stdin, stdout, and stderr, and exits with a zero exit
	 328  // status.
	 329  //
	 330  // If the command starts but does not complete successfully, the error is of
	 331  // type *ExitError. Other error types may be returned for other situations.
	 332  //
	 333  // If the calling goroutine has locked the operating system thread
	 334  // with runtime.LockOSThread and modified any inheritable OS-level
	 335  // thread state (for example, Linux or Plan 9 name spaces), the new
	 336  // process will inherit the caller's thread state.
	 337  func (c *Cmd) Run() error {
	 338  	if err := c.Start(); err != nil {
	 339  		return err
	 340  	}
	 341  	return c.Wait()
	 342  }
	 343  
	 344  // lookExtensions finds windows executable by its dir and path.
	 345  // It uses LookPath to try appropriate extensions.
	 346  // lookExtensions does not search PATH, instead it converts `prog` into `.\prog`.
	 347  func lookExtensions(path, dir string) (string, error) {
	 348  	if filepath.Base(path) == path {
	 349  		path = filepath.Join(".", path)
	 350  	}
	 351  	if dir == "" {
	 352  		return LookPath(path)
	 353  	}
	 354  	if filepath.VolumeName(path) != "" {
	 355  		return LookPath(path)
	 356  	}
	 357  	if len(path) > 1 && os.IsPathSeparator(path[0]) {
	 358  		return LookPath(path)
	 359  	}
	 360  	dirandpath := filepath.Join(dir, path)
	 361  	// We assume that LookPath will only add file extension.
	 362  	lp, err := LookPath(dirandpath)
	 363  	if err != nil {
	 364  		return "", err
	 365  	}
	 366  	ext := strings.TrimPrefix(lp, dirandpath)
	 367  	return path + ext, nil
	 368  }
	 369  
	 370  // Start starts the specified command but does not wait for it to complete.
	 371  //
	 372  // If Start returns successfully, the c.Process field will be set.
	 373  //
	 374  // The Wait method will return the exit code and release associated resources
	 375  // once the command exits.
	 376  func (c *Cmd) Start() error {
	 377  	if c.Path == "" && c.lookPathErr == nil {
	 378  		c.lookPathErr = errors.New("exec: no command")
	 379  	}
	 380  	if c.lookPathErr != nil {
	 381  		c.closeDescriptors(c.closeAfterStart)
	 382  		c.closeDescriptors(c.closeAfterWait)
	 383  		return c.lookPathErr
	 384  	}
	 385  	if runtime.GOOS == "windows" {
	 386  		lp, err := lookExtensions(c.Path, c.Dir)
	 387  		if err != nil {
	 388  			c.closeDescriptors(c.closeAfterStart)
	 389  			c.closeDescriptors(c.closeAfterWait)
	 390  			return err
	 391  		}
	 392  		c.Path = lp
	 393  	}
	 394  	if c.Process != nil {
	 395  		return errors.New("exec: already started")
	 396  	}
	 397  	if c.ctx != nil {
	 398  		select {
	 399  		case <-c.ctx.Done():
	 400  			c.closeDescriptors(c.closeAfterStart)
	 401  			c.closeDescriptors(c.closeAfterWait)
	 402  			return c.ctx.Err()
	 403  		default:
	 404  		}
	 405  	}
	 406  
	 407  	c.childFiles = make([]*os.File, 0, 3+len(c.ExtraFiles))
	 408  	type F func(*Cmd) (*os.File, error)
	 409  	for _, setupFd := range []F{(*Cmd).stdin, (*Cmd).stdout, (*Cmd).stderr} {
	 410  		fd, err := setupFd(c)
	 411  		if err != nil {
	 412  			c.closeDescriptors(c.closeAfterStart)
	 413  			c.closeDescriptors(c.closeAfterWait)
	 414  			return err
	 415  		}
	 416  		c.childFiles = append(c.childFiles, fd)
	 417  	}
	 418  	c.childFiles = append(c.childFiles, c.ExtraFiles...)
	 419  
	 420  	envv, err := c.envv()
	 421  	if err != nil {
	 422  		return err
	 423  	}
	 424  
	 425  	c.Process, err = os.StartProcess(c.Path, c.argv(), &os.ProcAttr{
	 426  		Dir:	 c.Dir,
	 427  		Files: c.childFiles,
	 428  		Env:	 addCriticalEnv(dedupEnv(envv)),
	 429  		Sys:	 c.SysProcAttr,
	 430  	})
	 431  	if err != nil {
	 432  		c.closeDescriptors(c.closeAfterStart)
	 433  		c.closeDescriptors(c.closeAfterWait)
	 434  		return err
	 435  	}
	 436  
	 437  	c.closeDescriptors(c.closeAfterStart)
	 438  
	 439  	// Don't allocate the channel unless there are goroutines to fire.
	 440  	if len(c.goroutine) > 0 {
	 441  		c.errch = make(chan error, len(c.goroutine))
	 442  		for _, fn := range c.goroutine {
	 443  			go func(fn func() error) {
	 444  				c.errch <- fn()
	 445  			}(fn)
	 446  		}
	 447  	}
	 448  
	 449  	if c.ctx != nil {
	 450  		c.waitDone = make(chan struct{})
	 451  		go func() {
	 452  			select {
	 453  			case <-c.ctx.Done():
	 454  				c.Process.Kill()
	 455  			case <-c.waitDone:
	 456  			}
	 457  		}()
	 458  	}
	 459  
	 460  	return nil
	 461  }
	 462  
	 463  // An ExitError reports an unsuccessful exit by a command.
	 464  type ExitError struct {
	 465  	*os.ProcessState
	 466  
	 467  	// Stderr holds a subset of the standard error output from the
	 468  	// Cmd.Output method if standard error was not otherwise being
	 469  	// collected.
	 470  	//
	 471  	// If the error output is long, Stderr may contain only a prefix
	 472  	// and suffix of the output, with the middle replaced with
	 473  	// text about the number of omitted bytes.
	 474  	//
	 475  	// Stderr is provided for debugging, for inclusion in error messages.
	 476  	// Users with other needs should redirect Cmd.Stderr as needed.
	 477  	Stderr []byte
	 478  }
	 479  
	 480  func (e *ExitError) Error() string {
	 481  	return e.ProcessState.String()
	 482  }
	 483  
	 484  // Wait waits for the command to exit and waits for any copying to
	 485  // stdin or copying from stdout or stderr to complete.
	 486  //
	 487  // The command must have been started by Start.
	 488  //
	 489  // The returned error is nil if the command runs, has no problems
	 490  // copying stdin, stdout, and stderr, and exits with a zero exit
	 491  // status.
	 492  //
	 493  // If the command fails to run or doesn't complete successfully, the
	 494  // error is of type *ExitError. Other error types may be
	 495  // returned for I/O problems.
	 496  //
	 497  // If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits
	 498  // for the respective I/O loop copying to or from the process to complete.
	 499  //
	 500  // Wait releases any resources associated with the Cmd.
	 501  func (c *Cmd) Wait() error {
	 502  	if c.Process == nil {
	 503  		return errors.New("exec: not started")
	 504  	}
	 505  	if c.finished {
	 506  		return errors.New("exec: Wait was already called")
	 507  	}
	 508  	c.finished = true
	 509  
	 510  	state, err := c.Process.Wait()
	 511  	if c.waitDone != nil {
	 512  		close(c.waitDone)
	 513  	}
	 514  	c.ProcessState = state
	 515  
	 516  	var copyError error
	 517  	for range c.goroutine {
	 518  		if err := <-c.errch; err != nil && copyError == nil {
	 519  			copyError = err
	 520  		}
	 521  	}
	 522  
	 523  	c.closeDescriptors(c.closeAfterWait)
	 524  
	 525  	if err != nil {
	 526  		return err
	 527  	} else if !state.Success() {
	 528  		return &ExitError{ProcessState: state}
	 529  	}
	 530  
	 531  	return copyError
	 532  }
	 533  
	 534  // Output runs the command and returns its standard output.
	 535  // Any returned error will usually be of type *ExitError.
	 536  // If c.Stderr was nil, Output populates ExitError.Stderr.
	 537  func (c *Cmd) Output() ([]byte, error) {
	 538  	if c.Stdout != nil {
	 539  		return nil, errors.New("exec: Stdout already set")
	 540  	}
	 541  	var stdout bytes.Buffer
	 542  	c.Stdout = &stdout
	 543  
	 544  	captureErr := c.Stderr == nil
	 545  	if captureErr {
	 546  		c.Stderr = &prefixSuffixSaver{N: 32 << 10}
	 547  	}
	 548  
	 549  	err := c.Run()
	 550  	if err != nil && captureErr {
	 551  		if ee, ok := err.(*ExitError); ok {
	 552  			ee.Stderr = c.Stderr.(*prefixSuffixSaver).Bytes()
	 553  		}
	 554  	}
	 555  	return stdout.Bytes(), err
	 556  }
	 557  
	 558  // CombinedOutput runs the command and returns its combined standard
	 559  // output and standard error.
	 560  func (c *Cmd) CombinedOutput() ([]byte, error) {
	 561  	if c.Stdout != nil {
	 562  		return nil, errors.New("exec: Stdout already set")
	 563  	}
	 564  	if c.Stderr != nil {
	 565  		return nil, errors.New("exec: Stderr already set")
	 566  	}
	 567  	var b bytes.Buffer
	 568  	c.Stdout = &b
	 569  	c.Stderr = &b
	 570  	err := c.Run()
	 571  	return b.Bytes(), err
	 572  }
	 573  
	 574  // StdinPipe returns a pipe that will be connected to the command's
	 575  // standard input when the command starts.
	 576  // The pipe will be closed automatically after Wait sees the command exit.
	 577  // A caller need only call Close to force the pipe to close sooner.
	 578  // For example, if the command being run will not exit until standard input
	 579  // is closed, the caller must close the pipe.
	 580  func (c *Cmd) StdinPipe() (io.WriteCloser, error) {
	 581  	if c.Stdin != nil {
	 582  		return nil, errors.New("exec: Stdin already set")
	 583  	}
	 584  	if c.Process != nil {
	 585  		return nil, errors.New("exec: StdinPipe after process started")
	 586  	}
	 587  	pr, pw, err := os.Pipe()
	 588  	if err != nil {
	 589  		return nil, err
	 590  	}
	 591  	c.Stdin = pr
	 592  	c.closeAfterStart = append(c.closeAfterStart, pr)
	 593  	wc := &closeOnce{File: pw}
	 594  	c.closeAfterWait = append(c.closeAfterWait, wc)
	 595  	return wc, nil
	 596  }
	 597  
	 598  type closeOnce struct {
	 599  	*os.File
	 600  
	 601  	once sync.Once
	 602  	err	error
	 603  }
	 604  
	 605  func (c *closeOnce) Close() error {
	 606  	c.once.Do(c.close)
	 607  	return c.err
	 608  }
	 609  
	 610  func (c *closeOnce) close() {
	 611  	c.err = c.File.Close()
	 612  }
	 613  
	 614  // StdoutPipe returns a pipe that will be connected to the command's
	 615  // standard output when the command starts.
	 616  //
	 617  // Wait will close the pipe after seeing the command exit, so most callers
	 618  // need not close the pipe themselves. It is thus incorrect to call Wait
	 619  // before all reads from the pipe have completed.
	 620  // For the same reason, it is incorrect to call Run when using StdoutPipe.
	 621  // See the example for idiomatic usage.
	 622  func (c *Cmd) StdoutPipe() (io.ReadCloser, error) {
	 623  	if c.Stdout != nil {
	 624  		return nil, errors.New("exec: Stdout already set")
	 625  	}
	 626  	if c.Process != nil {
	 627  		return nil, errors.New("exec: StdoutPipe after process started")
	 628  	}
	 629  	pr, pw, err := os.Pipe()
	 630  	if err != nil {
	 631  		return nil, err
	 632  	}
	 633  	c.Stdout = pw
	 634  	c.closeAfterStart = append(c.closeAfterStart, pw)
	 635  	c.closeAfterWait = append(c.closeAfterWait, pr)
	 636  	return pr, nil
	 637  }
	 638  
	 639  // StderrPipe returns a pipe that will be connected to the command's
	 640  // standard error when the command starts.
	 641  //
	 642  // Wait will close the pipe after seeing the command exit, so most callers
	 643  // need not close the pipe themselves. It is thus incorrect to call Wait
	 644  // before all reads from the pipe have completed.
	 645  // For the same reason, it is incorrect to use Run when using StderrPipe.
	 646  // See the StdoutPipe example for idiomatic usage.
	 647  func (c *Cmd) StderrPipe() (io.ReadCloser, error) {
	 648  	if c.Stderr != nil {
	 649  		return nil, errors.New("exec: Stderr already set")
	 650  	}
	 651  	if c.Process != nil {
	 652  		return nil, errors.New("exec: StderrPipe after process started")
	 653  	}
	 654  	pr, pw, err := os.Pipe()
	 655  	if err != nil {
	 656  		return nil, err
	 657  	}
	 658  	c.Stderr = pw
	 659  	c.closeAfterStart = append(c.closeAfterStart, pw)
	 660  	c.closeAfterWait = append(c.closeAfterWait, pr)
	 661  	return pr, nil
	 662  }
	 663  
	 664  // prefixSuffixSaver is an io.Writer which retains the first N bytes
	 665  // and the last N bytes written to it. The Bytes() methods reconstructs
	 666  // it with a pretty error message.
	 667  type prefixSuffixSaver struct {
	 668  	N				 int // max size of prefix or suffix
	 669  	prefix		[]byte
	 670  	suffix		[]byte // ring buffer once len(suffix) == N
	 671  	suffixOff int		// offset to write into suffix
	 672  	skipped	 int64
	 673  
	 674  	// TODO(bradfitz): we could keep one large []byte and use part of it for
	 675  	// the prefix, reserve space for the '... Omitting N bytes ...' message,
	 676  	// then the ring buffer suffix, and just rearrange the ring buffer
	 677  	// suffix when Bytes() is called, but it doesn't seem worth it for
	 678  	// now just for error messages. It's only ~64KB anyway.
	 679  }
	 680  
	 681  func (w *prefixSuffixSaver) Write(p []byte) (n int, err error) {
	 682  	lenp := len(p)
	 683  	p = w.fill(&w.prefix, p)
	 684  
	 685  	// Only keep the last w.N bytes of suffix data.
	 686  	if overage := len(p) - w.N; overage > 0 {
	 687  		p = p[overage:]
	 688  		w.skipped += int64(overage)
	 689  	}
	 690  	p = w.fill(&w.suffix, p)
	 691  
	 692  	// w.suffix is full now if p is non-empty. Overwrite it in a circle.
	 693  	for len(p) > 0 { // 0, 1, or 2 iterations.
	 694  		n := copy(w.suffix[w.suffixOff:], p)
	 695  		p = p[n:]
	 696  		w.skipped += int64(n)
	 697  		w.suffixOff += n
	 698  		if w.suffixOff == w.N {
	 699  			w.suffixOff = 0
	 700  		}
	 701  	}
	 702  	return lenp, nil
	 703  }
	 704  
	 705  // fill appends up to len(p) bytes of p to *dst, such that *dst does not
	 706  // grow larger than w.N. It returns the un-appended suffix of p.
	 707  func (w *prefixSuffixSaver) fill(dst *[]byte, p []byte) (pRemain []byte) {
	 708  	if remain := w.N - len(*dst); remain > 0 {
	 709  		add := minInt(len(p), remain)
	 710  		*dst = append(*dst, p[:add]...)
	 711  		p = p[add:]
	 712  	}
	 713  	return p
	 714  }
	 715  
	 716  func (w *prefixSuffixSaver) Bytes() []byte {
	 717  	if w.suffix == nil {
	 718  		return w.prefix
	 719  	}
	 720  	if w.skipped == 0 {
	 721  		return append(w.prefix, w.suffix...)
	 722  	}
	 723  	var buf bytes.Buffer
	 724  	buf.Grow(len(w.prefix) + len(w.suffix) + 50)
	 725  	buf.Write(w.prefix)
	 726  	buf.WriteString("\n... omitting ")
	 727  	buf.WriteString(strconv.FormatInt(w.skipped, 10))
	 728  	buf.WriteString(" bytes ...\n")
	 729  	buf.Write(w.suffix[w.suffixOff:])
	 730  	buf.Write(w.suffix[:w.suffixOff])
	 731  	return buf.Bytes()
	 732  }
	 733  
	 734  func minInt(a, b int) int {
	 735  	if a < b {
	 736  		return a
	 737  	}
	 738  	return b
	 739  }
	 740  
	 741  // dedupEnv returns a copy of env with any duplicates removed, in favor of
	 742  // later values.
	 743  // Items not of the normal environment "key=value" form are preserved unchanged.
	 744  func dedupEnv(env []string) []string {
	 745  	return dedupEnvCase(runtime.GOOS == "windows", env)
	 746  }
	 747  
	 748  // dedupEnvCase is dedupEnv with a case option for testing.
	 749  // If caseInsensitive is true, the case of keys is ignored.
	 750  func dedupEnvCase(caseInsensitive bool, env []string) []string {
	 751  	out := make([]string, 0, len(env))
	 752  	saw := make(map[string]int, len(env)) // key => index into out
	 753  	for _, kv := range env {
	 754  		eq := strings.Index(kv, "=")
	 755  		if eq < 0 {
	 756  			out = append(out, kv)
	 757  			continue
	 758  		}
	 759  		k := kv[:eq]
	 760  		if caseInsensitive {
	 761  			k = strings.ToLower(k)
	 762  		}
	 763  		if dupIdx, isDup := saw[k]; isDup {
	 764  			out[dupIdx] = kv
	 765  			continue
	 766  		}
	 767  		saw[k] = len(out)
	 768  		out = append(out, kv)
	 769  	}
	 770  	return out
	 771  }
	 772  
	 773  // addCriticalEnv adds any critical environment variables that are required
	 774  // (or at least almost always required) on the operating system.
	 775  // Currently this is only used for Windows.
	 776  func addCriticalEnv(env []string) []string {
	 777  	if runtime.GOOS != "windows" {
	 778  		return env
	 779  	}
	 780  	for _, kv := range env {
	 781  		eq := strings.Index(kv, "=")
	 782  		if eq < 0 {
	 783  			continue
	 784  		}
	 785  		k := kv[:eq]
	 786  		if strings.EqualFold(k, "SYSTEMROOT") {
	 787  			// We already have it.
	 788  			return env
	 789  		}
	 790  	}
	 791  	return append(env, "SYSTEMROOT="+os.Getenv("SYSTEMROOT"))
	 792  }
	 793
View as plain text