The functions in this section let you interact with the current running process.
Often you will need to perform some cleanup tasks whenever the current process terminates normally. The functions in this section let you do that.
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:
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.
A collection of environment variables that can be passed to subprocesses.
Create a new cork_env containing all of the environment variables in the current process’s environment list.
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.
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.
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.
A specification for executing another program.
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 cork_add_param() function.
Most programs will expect the first parameter to be the name of the program being executed. The 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 cork_exec_run() function.
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 cork_exec_run()), which means you won’t have a chance to free the specification object.
Return a string description of the program described by an execution specification.
Add a parameter to the parameter list that will be passed into the new program.
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 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 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.
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.
Accessor functions that allow you to retrieve the contents of an execution specification. The cork_exec_env() and cork_exec_cwd() functions might return NULL, if there isn’t an environment or working directory specified.