environment.h File Reference

#include <stdio.h>
#include <stdlib.h>
#include <dirent.h>
#include "environment.h"

Include dependency graph for environment.h:

Go to the source code of this file.

Typedefs
typedef struct StrList	RuntimeEnv

Functions
ssize_t	runtime_contains (RuntimeEnv *env, const char *key)
RuntimeEnv *	runtime_copy (char **env)
int	runtime_replace (RuntimeEnv **dest, char **src)
char *	runtime_get (RuntimeEnv *env, const char *key)
void	runtime_set (RuntimeEnv *env, const char *_key, char *_value)
char *	runtime_expand_var (RuntimeEnv *env, char *input)
void	runtime_export (RuntimeEnv *env, char **keys)
void	runtime_apply (RuntimeEnv *env)
void	runtime_free (RuntimeEnv *env)

Function Documentation

runtime_apply()

void runtime_apply

(

RuntimeEnv *

env

)

Update the global environ array with data from RuntimeEnv

Parameters

env	RuntimeEnv structure

Here is the call graph for this function:

runtime_contains()

ssize_t runtime_contains	(	RuntimeEnv *	env,
		const char *	key )

Determine whether a key exists in the runtime environment

Example:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = runtime_copy(arge);
    if (runtime_contains(rt, "PATH") {
        // $PATH is present
    }
    else {
        // $PATH is NOT present
    }
 
    runtime_free(rt);
    return 0;
}

Parameters

env	RuntimeEnv structure
key	Environment variable string

Returns

-1=no, positive_value=yes

Here is the call graph for this function:

runtime_copy()

RuntimeEnv * runtime_copy

(

char **

env

)

Populate a RuntimeEnv structure

Example:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = NULL;
    // Example 1: Copy the shell environment
    rt = runtime_copy(arge);
    // Example 2: Create your own environment
    rt = runtime_copy((char *[]) {"SHELL=/bin/bash", "PATH=/opt/secure:/bin:/usr/bin"})
 
    runtime_free(rt);
    return 0;
}

Parameters

env	Array of strings in var=value format

Returns

RuntimeEnv structure

Here is the call graph for this function:

runtime_expand_var()

char * runtime_expand_var	(	RuntimeEnv *	env,
		char *	input )

Parse an input string and expand any environment variable(s) found

Example:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = runtime_copy(arge);
    char *secure_path = runtime_expand_var(rt, "/opt/secure:$PATH:/aux/bin");
    if (secure_path == NULL) {
        // handle error
    }
    // secure_path = "/opt/secure:/your/original/path/here:/aux/bin";
 
    runtime_free(rt);
    return 0;
}

Parameters

env	RuntimeEnv structure
input	String to parse

Returns

success=expanded string, failure=NULL

Here is the call graph for this function:

runtime_export()

void runtime_export	(	RuntimeEnv *	env,
		char **	keys )

Print a shell-specific listing of environment variables to stdout

Example:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = runtime_copy(arge);
    runtime_export(rt, NULL);
    runtime_free(rt);
    return 0;
}

Usage:

$ gcc program.c
$ ./a.out
PATH="/thing/stuff/bin:/example/please/bin"
SHELL="/your/shell"
CC="/your/compiler"
...=...
 
# You can also use this to modify the shell environment
# (use `runtime_set` to manipulate the output)
$ source $(./a.out)

Example of exporting specific keys from the environment:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = runtime_copy(arge);
 
    // inline declaration
    runtime_export(rt, (char *[]) {"PATH", "LS_COLORS", NULL});
 
    // standard declaration
    char *keys_to_export[] = {
        "PATH", "LS_COLORS", NULL
    }
    runtime_export(rt, keys_to_export);
 
    runtime_free(rt);
    return 0;
}

Parameters

env	RuntimeEnv structure
keys	Array of keys to export. A value of NULL exports all environment keys

Here is the call graph for this function:

runtime_free()

void runtime_free

(

RuntimeEnv *

env

)

Free RuntimeEnv allocated by runtime_copy

Parameters

env	RuntimeEnv structure

Here is the call graph for this function:

runtime_get()

char * runtime_get	(	RuntimeEnv *	env,
		const char *	key )

Retrieve the value of a runtime environment variable

Example:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = runtime_copy(arge);
    char *path = runtime_get("PATH");
    if (path == NULL) {
        // handle error
    }
 
    runtime_free(rt);
    return 0;
}

Parameters

env	RuntimeEnv structure
key	Environment variable string

Returns

success=string, failure=NULL

Here is the call graph for this function:

runtime_replace()

int runtime_replace	(	RuntimeEnv **	dest,
		char **	src )

Replace the contents of dest with src

Parameters

dest	pointer of type RuntimeEnv
src	pointer to environment array

Returns

0 on success, <0 on error

Here is the call graph for this function:

runtime_set()

void runtime_set	(	RuntimeEnv *	env,
		const char *	_key,
		char *	_value )

Set a runtime environment variable.

Note: _value is passed through runtime_expand_var to provide shell expansion

Example:

int main(int argc, char *argv[], char *arge[]) {
    RuntimeEnv *rt = runtime_copy(arge);
 
    runtime_set(rt, "new_var", "1");
    char *new_var = runtime_get("new_var");
    // new_var = 1;
 
    char *path = runtime_get("PATH");
    // path = /your/path:/here
 
    runtime_set(rt, "PATH", "/opt/secure:$PATH");
    char *secure_path = runtime_get("PATH");
    // secure_path = /opt/secure:/your/path:/here
    // NOTE: path and secure_path are COPIES, unlike `getenv()` and `setenv()` that reuse their pointers in `environ`
 
    runtime_free(rt);
    return 0;
}

Parameters

env	RuntimeEnv structure
_key	Environment variable to set
_value	New environment variable value

Here is the call graph for this function: