exec.go

Documentation: os

     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 os
     6  
     7  import (
     8  	"errors"
     9  	"internal/testlog"
    10  	"runtime"
    11  	"sync"
    12  	"sync/atomic"
    13  	"syscall"
    14  	"time"
    15  )
    16  
    17  // ErrProcessDone indicates a Process has finished.
    18  var ErrProcessDone = errors.New("os: process already finished")
    19  
    20  // Process stores the information about a process created by StartProcess.
    21  type Process struct {
    22  	Pid    int
    23  	handle uintptr      // handle is accessed atomically on Windows
    24  	isdone uint32       // process has been successfully waited on, non zero if true
    25  	sigMu  sync.RWMutex // avoid race between wait and signal
    26  }
    27  
    28  func newProcess(pid int, handle uintptr) *Process {
    29  	p := &Process{Pid: pid, handle: handle}
    30  	runtime.SetFinalizer(p, (*Process).Release)
    31  	return p
    32  }
    33  
    34  func (p *Process) setDone() {
    35  	atomic.StoreUint32(&p.isdone, 1)
    36  }
    37  
    38  func (p *Process) done() bool {
    39  	return atomic.LoadUint32(&p.isdone) > 0
    40  }
    41  
    42  // ProcAttr holds the attributes that will be applied to a new process
    43  // started by StartProcess.
    44  type ProcAttr struct {
    45  	// If Dir is non-empty, the child changes into the directory before
    46  	// creating the process.
    47  	Dir string
    48  	// If Env is non-nil, it gives the environment variables for the
    49  	// new process in the form returned by Environ.
    50  	// If it is nil, the result of Environ will be used.
    51  	Env []string
    52  	// Files specifies the open files inherited by the new process. The
    53  	// first three entries correspond to standard input, standard output, and
    54  	// standard error. An implementation may support additional entries,
    55  	// depending on the underlying operating system. A nil entry corresponds
    56  	// to that file being closed when the process starts.
    57  	Files []*File
    58  
    59  	// Operating system-specific process creation attributes.
    60  	// Note that setting this field means that your program
    61  	// may not execute properly or even compile on some
    62  	// operating systems.
    63  	Sys *syscall.SysProcAttr
    64  }
    65  
    66  // A Signal represents an operating system signal.
    67  // The usual underlying implementation is operating system-dependent:
    68  // on Unix it is syscall.Signal.
    69  type Signal interface {
    70  	String() string
    71  	Signal() // to distinguish from other Stringers
    72  }
    73  
    74  // Getpid returns the process id of the caller.
    75  func Getpid() int { return syscall.Getpid() }
    76  
    77  // Getppid returns the process id of the caller's parent.
    78  func Getppid() int { return syscall.Getppid() }
    79  
    80  // FindProcess looks for a running process by its pid.
    81  //
    82  // The Process it returns can be used to obtain information
    83  // about the underlying operating system process.
    84  //
    85  // On Unix systems, FindProcess always succeeds and returns a Process
    86  // for the given pid, regardless of whether the process exists.
    87  func FindProcess(pid int) (*Process, error) {
    88  	return findProcess(pid)
    89  }
    90  
    91  // StartProcess starts a new process with the program, arguments and attributes
    92  // specified by name, argv and attr. The argv slice will become os.Args in the
    93  // new process, so it normally starts with the program name.
    94  //
    95  // If the calling goroutine has locked the operating system thread
    96  // with runtime.LockOSThread and modified any inheritable OS-level
    97  // thread state (for example, Linux or Plan 9 name spaces), the new
    98  // process will inherit the caller's thread state.
    99  //
   100  // StartProcess is a low-level interface. The os/exec package provides
   101  // higher-level interfaces.
   102  //
   103  // If there is an error, it will be of type *PathError.
   104  func StartProcess(name string, argv []string, attr *ProcAttr) (*Process, error) {
   105  	testlog.Open(name)
   106  	return startProcess(name, argv, attr)
   107  }
   108  
   109  // Release releases any resources associated with the Process p,
   110  // rendering it unusable in the future.
   111  // Release only needs to be called if Wait is not.
   112  func (p *Process) Release() error {
   113  	return p.release()
   114  }
   115  
   116  // Kill causes the Process to exit immediately. Kill does not wait until
   117  // the Process has actually exited. This only kills the Process itself,
   118  // not any other processes it may have started.
   119  func (p *Process) Kill() error {
   120  	return p.kill()
   121  }
   122  
   123  // Wait waits for the Process to exit, and then returns a
   124  // ProcessState describing its status and an error, if any.
   125  // Wait releases any resources associated with the Process.
   126  // On most operating systems, the Process must be a child
   127  // of the current process or an error will be returned.
   128  func (p *Process) Wait() (*ProcessState, error) {
   129  	return p.wait()
   130  }
   131  
   132  // Signal sends a signal to the Process.
   133  // Sending Interrupt on Windows is not implemented.
   134  func (p *Process) Signal(sig Signal) error {
   135  	return p.signal(sig)
   136  }
   137  
   138  // UserTime returns the user CPU time of the exited process and its children.
   139  func (p *ProcessState) UserTime() time.Duration {
   140  	return p.userTime()
   141  }
   142  
   143  // SystemTime returns the system CPU time of the exited process and its children.
   144  func (p *ProcessState) SystemTime() time.Duration {
   145  	return p.systemTime()
   146  }
   147  
   148  // Exited reports whether the program has exited.
   149  func (p *ProcessState) Exited() bool {
   150  	return p.exited()
   151  }
   152  
   153  // Success reports whether the program exited successfully,
   154  // such as with exit status 0 on Unix.
   155  func (p *ProcessState) Success() bool {
   156  	return p.success()
   157  }
   158  
   159  // Sys returns system-dependent exit information about
   160  // the process. Convert it to the appropriate underlying
   161  // type, such as syscall.WaitStatus on Unix, to access its contents.
   162  func (p *ProcessState) Sys() interface{} {
   163  	return p.sys()
   164  }
   165  
   166  // SysUsage returns system-dependent resource usage information about
   167  // the exited process. Convert it to the appropriate underlying
   168  // type, such as *syscall.Rusage on Unix, to access its contents.
   169  // (On Unix, *syscall.Rusage matches struct rusage as defined in the
   170  // getrusage(2) manual page.)
   171  func (p *ProcessState) SysUsage() interface{} {
   172  	return p.sysUsage()
   173  }
   174
View as plain text