1new_process 2 3 SYNOPSIS 4 Create a subprocess object 5 6 USAGE 7 Struct_Type new_process (String_Type argv[]; qualifiers) 8 9 DESCRIPTION 10 This function executes the program specified by the `argv' 11 parameter in a subprocess. If `argv' is an array, the first 12 element (`argv[0]') of the array gives the name of the program 13 to be executed, and the remaining elements serve as arguments passed 14 to the program. The program returns a structure that may be used to 15 interact with the process. Upon error, an exception will be thrown. 16 17 The calling program may interact with the subprocess by reading from 18 or writing to the file descriptor fields of the structure returned 19 by the `new_process' function. The specific file descriptors 20 are dictated via the `read', `write', and `dupN' 21 qualifiers, as described in detail below. 22 23 The function returns a structure containing zero or more fields of the form 24 `fdN' where `N' is an integer derived from the qualifiers, 25 e.g., `fd0' and `fd1' correspond to the child's stdin and 26 stdout, respectively. The structure also contains fields of the 27 form `fpN' whose values are stdio File_Type objects 28 obtained using `fdopen' with the corresponding `fdN' value. 29 30 Other important fields include `pid' whose value is 31 the process-id of the newly created process. 32 33 The status of the process may be checked or collected using the 34 `wait' method. It is very important to call this method to 35 avoid the creation of zombie processes. 36 37 QUALIFIERS 38 The following qualifiers are supported: 39 40 read=fds 41 42 fds is a list of integer file descriptors that are open for read 43 access in the subprocess, and may be written to by the calling 44 process using the fdN or fpN fields of the structure. 45 46 write=fds 47 48 fds is a list of integer file descriptors that are open for write 49 access in the subprocess, and may be read to by the calling 50 process using the fdN or fpN fields of the structure. 51 52 stdin=filename 53 stdout=filename 54 stderr=filename 55 56 These qualifiers allow the stdin, stdout, and stderr file 57 descriptors in the subprocess to be redirected to a file. Note: 58 The filenames are interpreted relative to the value of the 59 `dir' qualifier. 60 61 fdN=string 62 63 This qualifier will cause the integer file descriptor N to be open 64 in the subprocess and redirected to the filename represented by 65 the string, which is interpreted relative to the value of the `dir' 66 qualifier. The access mode is dictated by the first few 67 characters of the string as described in more detail below. 68 69 stdin=File_Type|FD_Type 70 stdout=File_Type|FD_Type 71 stderr=File_Type|FD_Type 72 fdN=FD_Type|FD_Type 73 74 If the stdin, stdout, stderr, or fdN qualifiers have File_Type or 75 FD_Type values, then corresponding file descriptors in the 76 subprocess will be dup'd to FD_Type or FP_Type file descriptor. 77 This form of the qualifier may be used to setup pipelines. 78 79 dupN=int 80 81 The file descriptor corresponding to the integer N in the 82 subprocess is created by duping the descriptor given by the 83 integer value of the qualifier. For example, dup2=1 would cause 84 stderr (fd=2) in the subprocess to be redirected to stdout (fd=1). 85 86 dir=string 87 88 Change to the specified directory in the child process. This 89 will happen after the child process is started, but before any 90 files have been opened. Hence, files attached to `stdin', 91 `stdout', etc will be opened relative to this directory. 92 93 pre_exec_hook=&func 94 95 This qualifier will cause the function corresponding to `func' to 96 be called prior to closing unused file descriptors and invoking 97 the executable. The function will be passed a list of integer 98 valued file descriptors that will be kept open. Additional 99 integers may be added to the list by the function. If the 100 qualifier `pre_exec_hook_optarg' exists, it will also be 101 passed as an addtional argument. 102 103 pre_exec_hook_optarg=VALUE 104 105 If this qualifier exists, its value will be passed as the second 106 argument to the `pre_exec_hook' callback function. 107 108 Note that the read and write qualifiers specify the nature of the 109 file descriptors from the child process's view. That is, those 110 opened in the child process using the read qualifier, may be written 111 to by the parent. Similarly, those opened using the write qualifier 112 may be read by the parent. 113 114 METHODS 115 116 Struct_Type .wait ( [ options ] ) 117 118 The `.wait' method may be used to collect the exist status of 119 the process. When called without arguments, it will cause the 120 parent process to wait for the subprocess to exit and return its 121 exit status in the form of a `waitpid' structure. The optional 122 `options' argument corresponds to the options argument of the 123 `waitpid' function. The most common is the WNOHANG option, 124 which will cause the `.wait' method to return immediately if 125 the process has not exited. 126 127 If an error occurs, the function will return NULL and set 128 `errno' accordingly. Otherwise it will return a `waitpid' 129 structure. See the documentation for `waitpid' for more 130 information. 131 132 EXAMPLE 133 In the following examples, `pgm' represents the program to be 134 invoked in the subprocess. For simplicity, no addition arguments are 135 shown 136 137 Create subprocess that inherits stdin, stdout, stderr from the caller: 138 139 obj = new_process (pgm); 140 141 142 Create a subprocess that inherits stdin, stdout, and writes stderr 143 to a file: 144 145 obj = new_process (pgm; stderr="/tmp/file"); % form 1 146 obj = new_process (pgm; fd2=">/tmp/file"); % form 2 147 148 149 Mimic popen(pgm, "r"): 150 151 obj = new_process (pgm; write=1); % Read from obj.fp1 152 153 154 Mimic popen(pgm, "w"): 155 156 obj = new_process (pgm; read=0); % Write to obj.fp0 157 158 159 Mimic popen("pgm 2>&1", "r"): 160 161 obj = new_process (pgm; write=1, dup2=1); % Read from fp1 162 163 164 Send stdout to a file, read from the subprocess's stderr: 165 166 obj = new_process (pgm; stdout="/tmp/file", write=2); 167 % Read from obj.fp2 168 169 170 Create a process with handles to its stdin, stdout, stderr 171 172 obj = new_process (pgm; write={1,2}, read=0); 173 % Use obj.fp0 for stdin, obj.fp1 for stdout, and obj.fp2 for stderr 174 175 176 Create a process with a write handle to the process's fd=27 and a 177 read handle to the process's stdout. 178 179 obj = new_process (pgm; read=27, write=1); 180 % write to fp27, read from fp1 181 182 183 Create a pipeline: pgm1 | pgm2 > /tmp/log : 184 185 obj1 = new_process (pgm1; write=1); 186 obj2 = new_process (pgm2; stdin=obj1.fp1, stdout="/tmp/log"); 187 188 189 Create a pipeline with fd=27 from pgm1 redirected to stdin of pgm2: 190 191 obj1 = new_process (pgm1; write=27); 192 obj2 = new_process (pgm2; stdin=obj1.fp27); 193 194 195 Create a pipeline with fd=27 from pgm1 redirected to fd=9 of pgm2: 196 197 obj1 = new_process (pgm1; write=27); 198 obj2 = new_process (pgm2; fp9=obj1.fp27); 199 200 201 Mimic: pgm 2>&1 1>/dev/null 202 203 obj = new_process (pgm; fp2=1, stdout="/dev/null"); 204 205 206 Mimic: pgm >/dev/null 2>&1 207 208 obj = new_process (pgm; stdout="/dev/null", dup2=1); 209 210 211 Append the output of pgm to /tmp/file.log: 212 213 obj = new_process (pgm; stdout=">>/tmp/file.log"); 214 215 216 NOTES 217 Care must be exercised when reading or writing to multiple file 218 descriptors of a subprocess to avoid deadlock. In such cases, the 219 select module should be used, or the file descriptors could be put in 220 non-blocking mode via the fcntl module. 221 222 It is important to call the `.wait' method prevent the process 223 from becoming a zombie and clogging the process table. 224 225 SEE ALSO 226 popen, system 227 228-------------------------------------------------------------- 229