Environment Variables

Functions
bool	envGet (string *out, strref name)
bool	envSet (strref name, strref val)
bool	envUnset (strref name)
bool	envEnum (hashtable *out)
bool	envExists (strref name)

Detailed Description

Reads and changes the environment variables of the running process.

A variable set to an empty string still exists. Removing one completely is a separate call, envUnset(), because "set to empty" and "not set at all" are different states and a program reading the variable can tell them apart.

Name case

Windows matches variable names without regard to case, so PATH and Path are the same variable there. Unix matches them exactly, so they are two different variables. cx does not hide this difference, because the programs and libraries that read these variables do not hide it either. envEnum() builds its table to match the platform, so looking a name up in that table gives the same answer the platform itself would give.

Thread safety

cx locks its own environment calls, so envGet(), envSet(), envUnset() and envEnum() are safe to call from several threads at once.

That lock does not cover calls cx does not make. On Unix, changing the environment while another thread reads it with a plain getenv() – from the C library, or from any other library in the process – can crash, and cx cannot prevent that from outside. Set the variables a program needs during startup, before it starts any threads, and leave the environment alone after that. Windows does not have this problem.

Function Documentation

envEnum()

bool envEnum

(

hashtable *

out

)

Reads the entire environment into a hashtable of name to value.

This initializes the table itself, so pass an uninitialized hashtable. Destroy it with htDestroy() when finished.

Parameters

out	Receives a new string-to-string table

Returns

true on success

Example:

hashtable env;
envEnum(&env);
foreach (hashtable, it, env) {
    string name = htiKey(string, it);
    string val  = htiVal(string, it);
    // use name and val
}
htDestroy(&env);

envExists()

bool envExists ( strref  name )

inline

Checks whether an environment variable is set.

Parameters

name	Variable name

Returns

true if the variable is set

Example:

if (envExists(_SL("CX_DEBUG"))) {
    // variable is present
}

Definition at line 114 of file env.h.

References envGet(), and strDestroy().

envGet()

bool envGet	(	string *	out,
		strref	name
	)

Reads an environment variable.

Parameters

out	Receives the value, or is set to empty if the variable is not set
name	Variable name

Returns

true if the variable is set, false if it is not

Example:

string home = 0;
if (envGet(&home, _SL("HOME"))) {
    // use home
}
strDestroy(&home);

Referenced by envExists().

envSet()

bool envSet	(	strref	name,
		strref	val
	)

Sets an environment variable, creating it or replacing whatever value it had.

Parameters

name	Variable name; must not be empty and must not contain '='
val	Value to set; NULL or empty gives the variable an empty value

Returns

true on success

Example:

envSet(_SL("CX_MODE"), _SL("fast"));

envUnset()

bool envUnset

(

strref

name

)

Removes an environment variable.

Succeeds whether or not the variable was set to begin with.

Parameters

name	Variable name

Returns

true on success

Example:

envUnset(_SL("CX_MODE"));