Mercurial > hg > CbC > CbC_gcc
annotate libiberty/pexecute.txh @ 108:7ad14f446135
add CbC-example/rectypeTest/
| author | Nobuyasu Oshiro <dimolto@cr.ie.u-ryukyu.ac.jp> |
|---|---|
| date | Thu, 14 Jun 2012 20:30:24 +0900 |
| parents | f6334be47118 |
| children |
| rev | line source |
|---|---|
| 0 | 1 @c -*- mode: texinfo -*- |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
2 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
3 const char *@var{pname}, const char *@var{tempbase}) |
| 0 | 4 |
| 5 Prepare to execute one or more programs, with standard output of each | |
| 6 program fed to standard input of the next. This is a system | |
| 7 independent interface to execute a pipeline. | |
| 8 | |
| 9 @var{flags} is a bitwise combination of the following: | |
| 10 | |
| 11 @table @code | |
| 12 | |
| 13 @vindex PEX_RECORD_TIMES | |
| 14 @item PEX_RECORD_TIMES | |
| 15 Record subprocess times if possible. | |
| 16 | |
| 17 @vindex PEX_USE_PIPES | |
| 18 @item PEX_USE_PIPES | |
| 19 Use pipes for communication between processes, if possible. | |
| 20 | |
| 21 @vindex PEX_SAVE_TEMPS | |
| 22 @item PEX_SAVE_TEMPS | |
| 23 Don't delete temporary files used for communication between | |
| 24 processes. | |
| 25 | |
| 26 @end table | |
| 27 | |
| 28 @var{pname} is the name of program to be executed, used in error | |
| 29 messages. @var{tempbase} is a base name to use for any required | |
| 30 temporary files; it may be @code{NULL} to use a randomly chosen name. | |
| 31 | |
| 32 @end deftypefn | |
| 33 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
34 @deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
35 int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
36 const char *@var{outname}, const char *@var{errname}, int *@var{err}) |
| 0 | 37 |
| 38 Execute one program in a pipeline. On success this returns | |
| 39 @code{NULL}. On failure it returns an error message, a statically | |
| 40 allocated string. | |
| 41 | |
| 42 @var{obj} is returned by a previous call to @code{pex_init}. | |
| 43 | |
| 44 @var{flags} is a bitwise combination of the following: | |
| 45 | |
| 46 @table @code | |
| 47 | |
| 48 @vindex PEX_LAST | |
| 49 @item PEX_LAST | |
| 50 This must be set on the last program in the pipeline. In particular, | |
| 51 it should be set when executing a single program. The standard output | |
| 52 of the program will be sent to @var{outname}, or, if @var{outname} is | |
| 53 @code{NULL}, to the standard output of the calling program. Do @emph{not} | |
| 54 set this bit if you want to call @code{pex_read_output} | |
| 55 (described below). After a call to @code{pex_run} with this bit set, | |
| 56 @var{pex_run} may no longer be called with the same @var{obj}. | |
| 57 | |
| 58 @vindex PEX_SEARCH | |
| 59 @item PEX_SEARCH | |
| 60 Search for the program using the user's executable search path. | |
| 61 | |
| 62 @vindex PEX_SUFFIX | |
| 63 @item PEX_SUFFIX | |
| 64 @var{outname} is a suffix. See the description of @var{outname}, | |
| 65 below. | |
| 66 | |
| 67 @vindex PEX_STDERR_TO_STDOUT | |
| 68 @item PEX_STDERR_TO_STDOUT | |
| 69 Send the program's standard error to standard output, if possible. | |
| 70 | |
| 71 @vindex PEX_BINARY_INPUT | |
| 72 @vindex PEX_BINARY_OUTPUT | |
| 73 @vindex PEX_BINARY_ERROR | |
| 74 @item PEX_BINARY_INPUT | |
| 75 @itemx PEX_BINARY_OUTPUT | |
| 76 @itemx PEX_BINARY_ERROR | |
| 77 The standard input (output or error) of the program should be read (written) in | |
| 78 binary mode rather than text mode. These flags are ignored on systems | |
| 79 which do not distinguish binary mode and text mode, such as Unix. For | |
| 80 proper behavior these flags should match appropriately---a call to | |
| 81 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a | |
| 82 call using @code{PEX_BINARY_INPUT}. | |
| 83 | |
| 84 @vindex PEX_STDERR_TO_PIPE | |
| 85 @item PEX_STDERR_TO_PIPE | |
| 86 Send the program's standard error to a pipe, if possible. This flag | |
| 87 cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This | |
| 88 flag can be specified only on the last program in pipeline. | |
| 89 | |
| 90 @end table | |
| 91 | |
| 92 @var{executable} is the program to execute. @var{argv} is the set of | |
| 93 arguments to pass to the program; normally @code{@var{argv}[0]} will | |
| 94 be a copy of @var{executable}. | |
| 95 | |
| 96 @var{outname} is used to set the name of the file to use for standard | |
| 97 output. There are two cases in which no output file will be used: | |
| 98 | |
| 99 @enumerate | |
| 100 @item | |
| 101 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} | |
| 102 was set in the call to @code{pex_init}, and the system supports pipes | |
| 103 | |
| 104 @item | |
| 105 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is | |
| 106 @code{NULL} | |
| 107 @end enumerate | |
| 108 | |
| 109 @noindent | |
| 110 Otherwise the code will use a file to hold standard | |
| 111 output. If @code{PEX_LAST} is not set, this file is considered to be | |
| 112 a temporary file, and it will be removed when no longer needed, unless | |
| 113 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. | |
| 114 | |
| 115 There are two cases to consider when setting the name of the file to | |
| 116 hold standard output. | |
| 117 | |
| 118 @enumerate | |
| 119 @item | |
| 120 @code{PEX_SUFFIX} is set in @var{flags}. In this case | |
| 121 @var{outname} may not be @code{NULL}. If the @var{tempbase} parameter | |
| 122 to @code{pex_init} was not @code{NULL}, then the output file name is | |
| 123 the concatenation of @var{tempbase} and @var{outname}. If | |
| 124 @var{tempbase} was @code{NULL}, then the output file name is a random | |
| 125 file name ending in @var{outname}. | |
| 126 | |
| 127 @item | |
| 128 @code{PEX_SUFFIX} was not set in @var{flags}. In this | |
| 129 case, if @var{outname} is not @code{NULL}, it is used as the output | |
| 130 file name. If @var{outname} is @code{NULL}, and @var{tempbase} was | |
| 131 not NULL, the output file name is randomly chosen using | |
| 132 @var{tempbase}. Otherwise the output file name is chosen completely | |
| 133 at random. | |
| 134 @end enumerate | |
| 135 | |
| 136 @var{errname} is the file name to use for standard error output. If | |
| 137 it is @code{NULL}, standard error is the same as the caller's. | |
| 138 Otherwise, standard error is written to the named file. | |
| 139 | |
| 140 On an error return, the code sets @code{*@var{err}} to an @code{errno} | |
| 141 value, or to 0 if there is no relevant @code{errno}. | |
| 142 | |
| 143 @end deftypefn | |
| 144 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
145 @deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
146 int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
147 char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
148 const char *@var{errname}, int *@var{err}) |
| 0 | 149 |
| 150 Execute one program in a pipeline, permitting the environment for the | |
| 151 program to be specified. Behaviour and parameters not listed below are | |
| 152 as for @code{pex_run}. | |
| 153 | |
| 154 @var{env} is the environment for the child process, specified as an array of | |
| 155 character pointers. Each element of the array should point to a string of the | |
| 156 form @code{VAR=VALUE}, with the exception of the last element that must be | |
| 157 @code{NULL}. | |
| 158 | |
| 159 @end deftypefn | |
| 160 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
161 @deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
162 int @var{flags}, const char *@var{in_name}) |
| 0 | 163 |
| 164 Return a stream for a temporary file to pass to the first program in | |
| 165 the pipeline as input. | |
| 166 | |
| 167 The name of the input file is chosen according to the same rules | |
| 168 @code{pex_run} uses to choose output file names, based on | |
| 169 @var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. | |
| 170 | |
| 171 Don't call @code{fclose} on the returned stream; the first call to | |
| 172 @code{pex_run} closes it automatically. | |
| 173 | |
| 174 If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in | |
| 175 binary mode; otherwise, open it in the default mode. Including | |
| 176 @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. | |
| 177 @end deftypefn | |
| 178 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
179 @deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
180 int @var{binary}) |
| 0 | 181 |
| 182 Return a stream @var{fp} for a pipe connected to the standard input of | |
| 183 the first program in the pipeline; @var{fp} is opened for writing. | |
| 184 You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call | |
| 185 that returned @var{obj}. | |
| 186 | |
| 187 You must close @var{fp} using @code{fclose} yourself when you have | |
| 188 finished writing data to the pipeline. | |
| 189 | |
| 190 The file descriptor underlying @var{fp} is marked not to be inherited | |
| 191 by child processes. | |
| 192 | |
| 193 On systems that do not support pipes, this function returns | |
| 194 @code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would | |
| 195 like to write code that is portable to all systems the @code{pex} | |
| 196 functions support, consider using @code{pex_input_file} instead. | |
| 197 | |
| 198 There are two opportunities for deadlock using | |
| 199 @code{pex_input_pipe}: | |
| 200 | |
| 201 @itemize @bullet | |
| 202 @item | |
| 203 Most systems' pipes can buffer only a fixed amount of data; a process | |
| 204 that writes to a full pipe blocks. Thus, if you write to @file{fp} | |
| 205 before starting the first process, you run the risk of blocking when | |
| 206 there is no child process yet to read the data and allow you to | |
| 207 continue. @code{pex_input_pipe} makes no promises about the | |
| 208 size of the pipe's buffer, so if you need to write any data at all | |
| 209 before starting the first process in the pipeline, consider using | |
| 210 @code{pex_input_file} instead. | |
| 211 | |
| 212 @item | |
| 213 Using @code{pex_input_pipe} and @code{pex_read_output} together | |
| 214 may also cause deadlock. If the output pipe fills up, so that each | |
| 215 program in the pipeline is waiting for the next to read more data, and | |
| 216 you fill the input pipe by writing more data to @var{fp}, then there | |
| 217 is no way to make progress: the only process that could read data from | |
| 218 the output pipe is you, but you are blocked on the input pipe. | |
| 219 | |
| 220 @end itemize | |
| 221 | |
| 222 @end deftypefn | |
| 223 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
224 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
225 int @var{binary}) |
| 0 | 226 |
| 227 Returns a @code{FILE} pointer which may be used to read the standard | |
| 228 output of the last program in the pipeline. When this is used, | |
| 229 @code{PEX_LAST} should not be used in a call to @code{pex_run}. After | |
| 230 this is called, @code{pex_run} may no longer be called with the same | |
| 231 @var{obj}. @var{binary} should be non-zero if the file should be | |
| 232 opened in binary mode. Don't call @code{fclose} on the returned file; | |
| 233 it will be closed by @code{pex_free}. | |
| 234 | |
| 235 @end deftypefn | |
| 236 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
237 @deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
238 int @var{binary}) |
| 0 | 239 |
| 240 Returns a @code{FILE} pointer which may be used to read the standard | |
| 241 error of the last program in the pipeline. When this is used, | |
| 242 @code{PEX_LAST} should not be used in a call to @code{pex_run}. After | |
| 243 this is called, @code{pex_run} may no longer be called with the same | |
| 244 @var{obj}. @var{binary} should be non-zero if the file should be | |
| 245 opened in binary mode. Don't call @code{fclose} on the returned file; | |
| 246 it will be closed by @code{pex_free}. | |
| 247 | |
| 248 @end deftypefn | |
| 249 | |
| 250 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
251 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
252 int @var{count}, int *@var{vector}) |
| 0 | 253 |
| 254 Returns the exit status of all programs run using @var{obj}. | |
| 255 @var{count} is the number of results expected. The results will be | |
| 256 placed into @var{vector}. The results are in the order of the calls | |
| 257 to @code{pex_run}. Returns 0 on error, 1 on success. | |
| 258 | |
| 259 @end deftypefn | |
| 260 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
261 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
262 int @var{count}, struct pex_time *@var{vector}) |
| 0 | 263 |
| 264 Returns the process execution times of all programs run using | |
| 265 @var{obj}. @var{count} is the number of results expected. The | |
| 266 results will be placed into @var{vector}. The results are in the | |
| 267 order of the calls to @code{pex_run}. Returns 0 on error, 1 on | |
| 268 success. | |
| 269 | |
| 270 @code{struct pex_time} has the following fields of the type | |
| 271 @code{unsigned long}: @code{user_seconds}, | |
| 272 @code{user_microseconds}, @code{system_seconds}, | |
| 273 @code{system_microseconds}. On systems which do not support reporting | |
| 274 process times, all the fields will be set to @code{0}. | |
| 275 | |
| 276 @end deftypefn | |
| 277 | |
| 278 @deftypefn Extension void pex_free (struct pex_obj @var{obj}) | |
| 279 | |
| 280 Clean up and free all data associated with @var{obj}. If you have not | |
| 281 yet called @code{pex_get_times} or @code{pex_get_status}, this will | |
| 282 try to kill the subprocesses. | |
| 283 | |
| 284 @end deftypefn | |
| 285 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
286 @deftypefn Extension {const char *} pex_one (int @var{flags}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
287 const char *@var{executable}, char * const *@var{argv}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
288 const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
289 int *@var{status}, int *@var{err}) |
| 0 | 290 |
| 291 An interface to permit the easy execution of a | |
| 292 single program. The return value and most of the parameters are as | |
| 293 for a call to @code{pex_run}. @var{flags} is restricted to a | |
| 294 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and | |
| 295 @code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if | |
| 296 @code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will | |
| 297 be set to the exit status of the program. | |
| 298 | |
| 299 @end deftypefn | |
| 300 | |
|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
301 @deftypefn Extension int pexecute (const char *@var{program}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
302 char * const *@var{argv}, const char *@var{this_pname}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
303 const char *@var{temp_base}, char **@var{errmsg_fmt}, @ |
|
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
304 char **@var{errmsg_arg}, int @var{flags}) |
| 0 | 305 |
| 306 This is the old interface to execute one or more programs. It is | |
| 307 still supported for compatibility purposes, but is no longer | |
| 308 documented. | |
| 309 | |
| 310 @end deftypefn | |
| 311 | |
| 312 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) | |
| 313 | |
| 314 Another part of the old execution interface. | |
| 315 | |
| 316 @end deftypefn |