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