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. Kill does not wait until 113 // the Process has actually exited. This only kills the Process itself, 114 // not any other processes it may have started. 115 func (p *Process) Kill() error { 116 return p.kill() 117 } 118 119 // Wait waits for the Process to exit, and then returns a 120 // ProcessState describing its status and an error, if any. 121 // Wait releases any resources associated with the Process. 122 // On most operating systems, the Process must be a child 123 // of the current process or an error will be returned. 124 func (p *Process) Wait() (*ProcessState, error) { 125 return p.wait() 126 } 127 128 // Signal sends a signal to the Process. 129 // Sending Interrupt on Windows is not implemented. 130 func (p *Process) Signal(sig Signal) error { 131 return p.signal(sig) 132 } 133 134 // UserTime returns the user CPU time of the exited process and its children. 135 func (p *ProcessState) UserTime() time.Duration { 136 return p.userTime() 137 } 138 139 // SystemTime returns the system CPU time of the exited process and its children. 140 func (p *ProcessState) SystemTime() time.Duration { 141 return p.systemTime() 142 } 143 144 // Exited reports whether the program has exited. 145 func (p *ProcessState) Exited() bool { 146 return p.exited() 147 } 148 149 // Success reports whether the program exited successfully, 150 // such as with exit status 0 on Unix. 151 func (p *ProcessState) Success() bool { 152 return p.success() 153 } 154 155 // Sys returns system-dependent exit information about 156 // the process. Convert it to the appropriate underlying 157 // type, such as syscall.WaitStatus on Unix, to access its contents. 158 func (p *ProcessState) Sys() interface{} { 159 return p.sys() 160 } 161 162 // SysUsage returns system-dependent resource usage information about 163 // the exited process. Convert it to the appropriate underlying 164 // type, such as *syscall.Rusage on Unix, to access its contents. 165 // (On Unix, *syscall.Rusage matches struct rusage as defined in the 166 // getrusage(2) manual page.) 167 func (p *ProcessState) SysUsage() interface{} { 168 return p.sysUsage() 169 } 170