.. _processes: ********* Processes ********* .. highlight:: c :: #include The functions in this section let you interact with the current running process. Cleanup functions ~~~~~~~~~~~~~~~~~ Often you will need to perform some cleanup tasks whenever the current process terminates normally. The functions in this section let you do that. .. function:: void cork_cleanup_at_exit(int priority, cork_cleanup_function function) void cork_cleanup_at_exit_named(const char \*name, int priority, cork_cleanup_function function) Register a *function* that should be called when the current process terminates. When multiple functions are registered, the order in which they are called is determined by their *priority* values --- functions with lower priorities will be called first. If any functions have the same priority value, there is no guarantee about the order in which they will be called. All cleanup functions must conform to the following signature: .. type:: void (\*cork_cleanup_function)(void) The ``_named`` variant lets you provide an explicit name for the cleanup function, which currently is only used when printing out debug messages. The plain variant automatically detects the name of *function*, so that you don't have to provide it explicitly. .. _env: Environment variables ~~~~~~~~~~~~~~~~~~~~~ .. type:: struct cork_env A collection of environment variables that can be passed to subprocesses. .. function:: struct cork_env \*cork_env_new(void) Create a new, empty collection of environment variables. .. function:: struct cork_env \*cork_env_clone_current(void) Create a new :c:type:`cork_env` containing all of the environment variables in the current process's environment list. .. function:: void cork_env_free(struct cork_env \*env) Free a collection of environment variables. .. function:: const char \*cork_env_get(struct cork_env \*env, const char \*name) Return the value of the environment variable with the given *name*. If there is no variable with that name, return ``NULL``. If *env* is ``NULL``, then the variable is retrieved from the current process environment; otherwise, it is retrieved from *env*. .. function:: void cork_env_add(struct cork_env \*env, const char \*name, const char \*value) void cork_env_add_printf(struct cork_env \*env, const char \*name, const char \*format, ...) void cork_env_add_vprintf(struct cork_env \*env, const char \*name, const char \*format, va_list args) Add a new environment variable with the given *name* and *value*. If there is already a variable with that name, it is overwritten. We make a copy of both *name* and *variable*, so it is safe to pass in temporary or reusable strings for either. The ``printf`` and ``vprintf`` variants construct the new variable's value from a ``printf``-like format string. If *env* is ``NULL``, then the new variable is added to the current process environment; otherwise, it is added to *env*. .. function:: void cork_env_remove(struct cork_env \*env, const char \*name) Remove the environment variable with the given *name*, if it exists. If there isn't any variable with that name, do nothing. If *env* is ``NULL``, then the variable is removed from the current process environment; otherwise, it is removed from *env*. .. function:: void cork_env_replace_current(struct cork_env \*env) Replace the current process's environment list with the contents of *env*. .. _exec: Executing another program ~~~~~~~~~~~~~~~~~~~~~~~~~ .. type:: struct cork_exec A specification for executing another program. .. function:: struct cork_exec \*cork_exec_new(const char \*program) struct cork_exec \*cork_exec_new_with_params(const char \*program, ...) struct cork_exec \*cork_exec_new_with_param_array(const char \*program, char \* const \*params) Create a new specification for executing *program*. *program* must either be an absolute path to an executable on the local filesystem, or the name of an executable that should be found in the current ``PATH``. The first variant creates a specification that initially doesn't contain any parameters to pass into the new program. The second variant allows you to pass in each argument as a separate parameter; you must ensure that you terminate the list of parameters with a ``NULL`` pointer. The third variant allows you to pass in a ``NULL``-terminated array of strings to use as an initial parameter list. For all three variants, you can add additional parameters before executing the new program via the :c:func:`cork_add_param` function. .. note:: Most programs will expect the first parameter to be the name of the program being executed. The :c:func:`cork_exec_new_with_params` function will automatically fill in this first parameter for you. The other constructor functions do not; when using them, it is your responsibility to provide this parameter, just like any other parameters to pass into the program. This function does not actually execute the program; that is handled by the :c:func:`cork_exec_run` function. .. function:: void cork_exec_free(struct cork_exec \*exec) Free an execution specification. You normally won't need to call this function; normally you'll replace the current process with the new program (by calling :c:func:`cork_exec_run`), which means you won't have a chance to free the specification object. .. function:: const char \*cork_exec_description(struct cork_exec \*exec) Return a string description of the program described by an execution specification. .. function:: void cork_exec_add_param(struct cork_exec \*exec, const char \*param) Add a parameter to the parameter list that will be passed into the new program. .. function:: void cork_exec_set_env(struct cork_exec \*exec, struct cork_env \*env) Provide a set of environment variables that will be passed into the new program. The subprocess's environment will contain only those variables defined in *env*. You can use the :c:func:`cork_env_clone_current` function to create a copy of the current process's environment, to use it as a base to add new variables or remove unsafe variables. We will take control of *env*, so you must **not** call :c:func:`cork_env_free` to free the environment yourself. If you don't call this function for a specification object, the new program will use the same environment as the calling process. .. function:: void cork_exec_set_cwd(struct cork_exec \*exec, const char \directory) Change the working directory that the new program will be called from. If you don't call this function for a specification object, the new program will be executed in the same working directory as the calling process. .. function:: const char \*cork_exec_program(struct cork_exec \*exec) size_t \*cork_exec_param_count(struct cork_exec \*exec) const char \*cork_exec_param(struct cork_exec \*exec, size_t index) struct cork_env \*cork_exec_env(struct cork_exec \*exec) const char \*cork_exec_cwd(struct cork_exec \*exec) Accessor functions that allow you to retrieve the contents of an execution specification. The :c:func:`cork_exec_env` and :c:func:`cork_exec_cwd` functions might return ``NULL``, if there isn't an environment or working directory specified. .. function:: int cork_exec_run(struct cork_exec \*exec) Execute the program specified by *exec*, replacing the current process. If we can successfully start the new program, this function will not return. If there are any errors starting the program, this function will return an error condition.