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