Source file src/os/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