Source file src/pkg/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	package exec
     9	
    10	import (
    11		"bytes"
    12		"errors"
    13		"io"
    14		"os"
    15		"strconv"
    16		"syscall"
    17	)
    18	
    19	// Error records the name of a binary that failed to be be executed
    20	// and the reason it failed.
    21	type Error struct {
    22		Name string
    23		Err  error
    24	}
    25	
    26	func (e *Error) Error() string {
    27		return "exec: " + strconv.Quote(e.Name) + ": " + e.Err.Error()
    28	}
    29	
    30	// Cmd represents an external command being prepared or run.
    31	type Cmd struct {
    32		// Path is the path of the command to run.
    33		//
    34		// This is the only field that must be set to a non-zero
    35		// value.
    36		Path string
    37	
    38		// Args holds command line arguments, including the command as Args[0].
    39		// If the Args field is empty or nil, Run uses {Path}.
    40		// 
    41		// In typical use, both Path and Args are set by calling Command.
    42		Args []string
    43	
    44		// Env specifies the environment of the process.
    45		// If Env is nil, Run uses the current process's environment.
    46		Env []string
    47	
    48		// Dir specifies the working directory of the command.
    49		// If Dir is the empty string, Run runs the command in the
    50		// calling process's current directory.
    51		Dir string
    52	
    53		// Stdin specifies the process's standard input. If Stdin is
    54		// nil, the process reads from the null device (os.DevNull).
    55		Stdin io.Reader
    56	
    57		// Stdout and Stderr specify the process's standard output and error.
    58		//
    59		// If either is nil, Run connects the corresponding file descriptor
    60		// to the null device (os.DevNull).
    61		//
    62		// If Stdout and Stderr are the same writer, at most one
    63		// goroutine at a time will call Write.
    64		Stdout io.Writer
    65		Stderr io.Writer
    66	
    67		// ExtraFiles specifies additional open files to be inherited by the
    68		// new process. It does not include standard input, standard output, or
    69		// standard error. If non-nil, entry i becomes file descriptor 3+i.
    70		//
    71		// BUG: on OS X 10.6, child processes may sometimes inherit unwanted fds.
    72		// http://golang.org/issue/2603
    73		ExtraFiles []*os.File
    74	
    75		// SysProcAttr holds optional, operating system-specific attributes.
    76		// Run passes it to os.StartProcess as the os.ProcAttr's Sys field.
    77		SysProcAttr *syscall.SysProcAttr
    78	
    79		// Process is the underlying process, once started.
    80		Process *os.Process
    81	
    82		// ProcessState contains information about an exited process,
    83		// available after a call to Wait or Run.
    84		ProcessState *os.ProcessState
    85	
    86		err             error // last error (from LookPath, stdin, stdout, stderr)
    87		finished        bool  // when Wait was called
    88		childFiles      []*os.File
    89		closeAfterStart []io.Closer
    90		closeAfterWait  []io.Closer
    91		goroutine       []func() error
    92		errch           chan error // one send per goroutine
    93	}
    94	
    95	// Command returns the Cmd struct to execute the named program with
    96	// the given arguments.
    97	//
    98	// It sets Path and Args in the returned structure and zeroes the
    99	// other fields.
   100	//
   101	// If name contains no path separators, Command uses LookPath to
   102	// resolve the path to a complete name if possible. Otherwise it uses
   103	// name directly.
   104	//
   105	// The returned Cmd's Args field is constructed from the command name
   106	// followed by the elements of arg, so arg should not include the
   107	// command name itself. For example, Command("echo", "hello")
   108	func Command(name string, arg ...string) *Cmd {
   109		aname, err := LookPath(name)
   110		if err != nil {
   111			aname = name
   112		}
   113		return &Cmd{
   114			Path: aname,
   115			Args: append([]string{name}, arg...),
   116			err:  err,
   117		}
   118	}
   119	
   120	// interfaceEqual protects against panics from doing equality tests on
   121	// two interfaces with non-comparable underlying types
   122	func interfaceEqual(a, b interface{}) bool {
   123		defer func() {
   124			recover()
   125		}()
   126		return a == b
   127	}
   128	
   129	func (c *Cmd) envv() []string {
   130		if c.Env != nil {
   131			return c.Env
   132		}
   133		return os.Environ()
   134	}
   135	
   136	func (c *Cmd) argv() []string {
   137		if len(c.Args) > 0 {
   138			return c.Args
   139		}
   140		return []string{c.Path}
   141	}
   142	
   143	func (c *Cmd) stdin() (f *os.File, err error) {
   144		if c.Stdin == nil {
   145			f, err = os.Open(os.DevNull)
   146			c.closeAfterStart = append(c.closeAfterStart, f)
   147			return
   148		}
   149	
   150		if f, ok := c.Stdin.(*os.File); ok {
   151			return f, nil
   152		}
   153	
   154		pr, pw, err := os.Pipe()
   155		if err != nil {
   156			return
   157		}
   158	
   159		c.closeAfterStart = append(c.closeAfterStart, pr)
   160		c.closeAfterWait = append(c.closeAfterWait, pw)
   161		c.goroutine = append(c.goroutine, func() error {
   162			_, err := io.Copy(pw, c.Stdin)
   163			if err1 := pw.Close(); err == nil {
   164				err = err1
   165			}
   166			return err
   167		})
   168		return pr, nil
   169	}
   170	
   171	func (c *Cmd) stdout() (f *os.File, err error) {
   172		return c.writerDescriptor(c.Stdout)
   173	}
   174	
   175	func (c *Cmd) stderr() (f *os.File, err error) {
   176		if c.Stderr != nil && interfaceEqual(c.Stderr, c.Stdout) {
   177			return c.childFiles[1], nil
   178		}
   179		return c.writerDescriptor(c.Stderr)
   180	}
   181	
   182	func (c *Cmd) writerDescriptor(w io.Writer) (f *os.File, err error) {
   183		if w == nil {
   184			f, err = os.OpenFile(os.DevNull, os.O_WRONLY, 0)
   185			c.closeAfterStart = append(c.closeAfterStart, f)
   186			return
   187		}
   188	
   189		if f, ok := w.(*os.File); ok {
   190			return f, nil
   191		}
   192	
   193		pr, pw, err := os.Pipe()
   194		if err != nil {
   195			return
   196		}
   197	
   198		c.closeAfterStart = append(c.closeAfterStart, pw)
   199		c.closeAfterWait = append(c.closeAfterWait, pr)
   200		c.goroutine = append(c.goroutine, func() error {
   201			_, err := io.Copy(w, pr)
   202			return err
   203		})
   204		return pw, nil
   205	}
   206	
   207	// Run starts the specified command and waits for it to complete.
   208	//
   209	// The returned error is nil if the command runs, has no problems
   210	// copying stdin, stdout, and stderr, and exits with a zero exit
   211	// status.
   212	//
   213	// If the command fails to run or doesn't complete successfully, the
   214	// error is of type *ExitError. Other error types may be
   215	// returned for I/O problems.
   216	func (c *Cmd) Run() error {
   217		if err := c.Start(); err != nil {
   218			return err
   219		}
   220		return c.Wait()
   221	}
   222	
   223	// Start starts the specified command but does not wait for it to complete.
   224	func (c *Cmd) Start() error {
   225		if c.err != nil {
   226			return c.err
   227		}
   228		if c.Process != nil {
   229			return errors.New("exec: already started")
   230		}
   231	
   232		type F func(*Cmd) (*os.File, error)
   233		for _, setupFd := range []F{(*Cmd).stdin, (*Cmd).stdout, (*Cmd).stderr} {
   234			fd, err := setupFd(c)
   235			if err != nil {
   236				return err
   237			}
   238			c.childFiles = append(c.childFiles, fd)
   239		}
   240		c.childFiles = append(c.childFiles, c.ExtraFiles...)
   241	
   242		var err error
   243		c.Process, err = os.StartProcess(c.Path, c.argv(), &os.ProcAttr{
   244			Dir:   c.Dir,
   245			Files: c.childFiles,
   246			Env:   c.envv(),
   247			Sys:   c.SysProcAttr,
   248		})
   249		if err != nil {
   250			return err
   251		}
   252	
   253		for _, fd := range c.closeAfterStart {
   254			fd.Close()
   255		}
   256	
   257		c.errch = make(chan error, len(c.goroutine))
   258		for _, fn := range c.goroutine {
   259			go func(fn func() error) {
   260				c.errch <- fn()
   261			}(fn)
   262		}
   263	
   264		return nil
   265	}
   266	
   267	// An ExitError reports an unsuccessful exit by a command.
   268	type ExitError struct {
   269		*os.ProcessState
   270	}
   271	
   272	func (e *ExitError) Error() string {
   273		return e.ProcessState.String()
   274	}
   275	
   276	// Wait waits for the command to exit.
   277	// It must have been started by Start.
   278	//
   279	// The returned error is nil if the command runs, has no problems
   280	// copying stdin, stdout, and stderr, and exits with a zero exit
   281	// status.
   282	//
   283	// If the command fails to run or doesn't complete successfully, the
   284	// error is of type *ExitError. Other error types may be
   285	// returned for I/O problems.
   286	func (c *Cmd) Wait() error {
   287		if c.Process == nil {
   288			return errors.New("exec: not started")
   289		}
   290		if c.finished {
   291			return errors.New("exec: Wait was already called")
   292		}
   293		c.finished = true
   294		state, err := c.Process.Wait()
   295		c.ProcessState = state
   296	
   297		var copyError error
   298		for _ = range c.goroutine {
   299			if err := <-c.errch; err != nil && copyError == nil {
   300				copyError = err
   301			}
   302		}
   303	
   304		for _, fd := range c.closeAfterWait {
   305			fd.Close()
   306		}
   307	
   308		if err != nil {
   309			return err
   310		} else if !state.Success() {
   311			return &ExitError{state}
   312		}
   313	
   314		return copyError
   315	}
   316	
   317	// Output runs the command and returns its standard output.
   318	func (c *Cmd) Output() ([]byte, error) {
   319		if c.Stdout != nil {
   320			return nil, errors.New("exec: Stdout already set")
   321		}
   322		var b bytes.Buffer
   323		c.Stdout = &b
   324		err := c.Run()
   325		return b.Bytes(), err
   326	}
   327	
   328	// CombinedOutput runs the command and returns its combined standard
   329	// output and standard error.
   330	func (c *Cmd) CombinedOutput() ([]byte, error) {
   331		if c.Stdout != nil {
   332			return nil, errors.New("exec: Stdout already set")
   333		}
   334		if c.Stderr != nil {
   335			return nil, errors.New("exec: Stderr already set")
   336		}
   337		var b bytes.Buffer
   338		c.Stdout = &b
   339		c.Stderr = &b
   340		err := c.Run()
   341		return b.Bytes(), err
   342	}
   343	
   344	// StdinPipe returns a pipe that will be connected to the command's
   345	// standard input when the command starts.
   346	func (c *Cmd) StdinPipe() (io.WriteCloser, error) {
   347		if c.Stdin != nil {
   348			return nil, errors.New("exec: Stdin already set")
   349		}
   350		if c.Process != nil {
   351			return nil, errors.New("exec: StdinPipe after process started")
   352		}
   353		pr, pw, err := os.Pipe()
   354		if err != nil {
   355			return nil, err
   356		}
   357		c.Stdin = pr
   358		c.closeAfterStart = append(c.closeAfterStart, pr)
   359		c.closeAfterWait = append(c.closeAfterWait, pw)
   360		return pw, nil
   361	}
   362	
   363	// StdoutPipe returns a pipe that will be connected to the command's
   364	// standard output when the command starts.
   365	// The pipe will be closed automatically after Wait sees the command exit.
   366	func (c *Cmd) StdoutPipe() (io.ReadCloser, error) {
   367		if c.Stdout != nil {
   368			return nil, errors.New("exec: Stdout already set")
   369		}
   370		if c.Process != nil {
   371			return nil, errors.New("exec: StdoutPipe after process started")
   372		}
   373		pr, pw, err := os.Pipe()
   374		if err != nil {
   375			return nil, err
   376		}
   377		c.Stdout = pw
   378		c.closeAfterStart = append(c.closeAfterStart, pw)
   379		c.closeAfterWait = append(c.closeAfterWait, pr)
   380		return pr, nil
   381	}
   382	
   383	// StderrPipe returns a pipe that will be connected to the command's
   384	// standard error when the command starts.
   385	// The pipe will be closed automatically after Wait sees the command exit.
   386	func (c *Cmd) StderrPipe() (io.ReadCloser, error) {
   387		if c.Stderr != nil {
   388			return nil, errors.New("exec: Stderr already set")
   389		}
   390		if c.Process != nil {
   391			return nil, errors.New("exec: StderrPipe after process started")
   392		}
   393		pr, pw, err := os.Pipe()
   394		if err != nil {
   395			return nil, err
   396		}
   397		c.Stderr = pw
   398		c.closeAfterStart = append(c.closeAfterStart, pw)
   399		c.closeAfterWait = append(c.closeAfterWait, pr)
   400		return pr, nil
   401	}