Processes

#include <libcork/os.h>

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.

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:

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.

Environment variables

struct cork_env

A collection of environment variables that can be passed to subprocesses.

struct cork_env *cork_env_new(void)

Create a new, empty collection of environment variables.

struct cork_env *cork_env_clone_current(void)

Create a new cork_env containing all of the environment variables in the current process’s environment list.

void cork_env_free(struct cork_env *env)

Free a collection of environment variables.

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.

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.

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.

void cork_env_replace_current(struct cork_env *env)

Replace the current process’s environment list with the contents of env.

Executing another program

struct cork_exec

A specification for executing another program.

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 cork_add_param() function.

Note

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.

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 cork_exec_run()), which means you won’t have a chance to free the specification object.

const char *cork_exec_description(struct cork_exec *exec)

Return a string description of the program described by an execution specification.

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.

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 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.

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.

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 cork_exec_env() and cork_exec_cwd() functions might return NULL, if there isn’t an environment or working directory specified.

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.