When a program is executed, it receives information about the context in which it was invoked in two ways. The first mechanism uses the argv and argc arguments to its main function, and is discussed in the section called “Program Arguments”. The second mechanism uses environment variables and is discussed in this section.
The argv mechanism is typically used to pass command-line arguments specific to the particular program being invoked. The environment, on the other hand, keeps track of information that is shared by many programs, changes infrequently, and that is less frequently used.
The environment variables discussed in this section are the same environment variables that you set using assignments and the export command in the shell. Programs executed from the shell inherit all of the environment variables from the shell.
Standard environment variables are used for information about the user's home directory, terminal type, current locale, and so on; you can define additional variables for other purposes. The set of all environment variables that have values is collectively known as the environment.
Names of environment variables are case-sensitive and must not contain the character =. System-defined environment variables are invariably uppercase.
The values of environment variables can be anything that can be represented as a string. A value must not contain an embedded null character, since this is assumed to terminate the string.
The value of an environment variable can be accessed with the getenv function. This is declared in the header file stdlib.h. All of the following functions can be safely used in multi-threaded programs. It is made sure that concurrent modifications to the environment do not lead to errors. char * function>getenv/function> (const char *name) This function returns a string that is the value of the environment variable name. You must not modify this string. In some non-Unix systems not using the GNU library, it might be overwritten by subsequent calls to getenv (but not by any other library function). If the environment variable name is not defined, the value is a null pointer.
int function>putenv/function> (char *string) The putenv function adds or removes definitions from the environment. If the string is of the form name=value, the definition is added to the environment. Otherwise, the string is interpreted as the name of an environment variable, and any definition for this variable in the environment is removed.
The difference to the setenv function is that the exact string given as the parameter string is put into the environment. If the user should change the string after the putenv call this will reflect in automatically in the environment. This also requires that string is no automatic variable which scope is left before the variable is removed from the environment. The same applies of course to dynamically allocated variables which are freed later.
This function is part of the extended Unix interface. Since it was also available in old SVID libraries you should define either _XOPEN_SOURCE or _SVID_SOURCE before including any header.
int function>setenv/function> (const char *name, const char *value, int replace) The setenv function can be used to add a new definition to the environment. The entry with the name name is replaced by the value name=value. Please note that this is also true if value is the empty string. To do this a new string is created and the strings name and value are copied. A null pointer for the value parameter is illegal. If the environment already contains an entry with key name the replace parameter controls the action. If replace is zero, nothing happens. Otherwise the old entry is replaced by the new one.
Please note that you cannot remove an entry completely using this function.
This function was originally part of the BSD library but is now part of the Unix standard.
int function>unsetenv/function> (const char *name) Using this function one can remove an entry completely from the environment. If the environment contains an entry with the key name this whole entry is removed. A call to this function is equivalent to a call to putenv when the value part of the string is empty.
The function return -1 if name is a null pointer, points to an empty string, or points to a string containing a = character. It returns 0 if the call succeeded.
This function was originally part of the BSD library but is now part of the Unix standard. The BSD version had no return value, though.
There is one more function to modify the whole environment. This function is said to be used in the POSIX.9 (POSIX bindings for Fortran 77) and so one should expect it did made it into POSIX.1. But this never happened. But we still provide this function as a GNU extension to enable writing standard compliant Fortran environments.
int function>clearenv/function> (void) The clearenv function removes all entries from the environment. Using putenv and setenv new entries can be added again later.
If the function is successful it returns 0. Otherwise the return value is nonzero.
You can deal directly with the underlying representation of environment objects to add more variables to the environment (for example, to communicate with another program you are about to execute; the section called “Executing a File”).
char ** function>environ/function> The environment is represented as an array of strings. Each string is of the format name=value. The order in which strings appear in the environment is not significant, but the same name must not appear more than once. The last element of the array is a null pointer.
This variable is declared in the header file unistd.h.
If you just want to get the value of an environment variable, use getenv.
Unix systems, and the GNU system, pass the initial value of environ as the third argument to main. the section called “Program Arguments”.
These environment variables have standard meanings. This doesn't mean that they are always present in the environment; but if these variables are present, they have these meanings. You shouldn't try to use these environment variable names for some other purpose.
This is a string representing the user's home directory, or initial default working directory.
The user can set HOME to any value. If you need to make sure to obtain the proper home directory for a particular user, you should not use HOME; instead, look up the user's name in the user database (the section called “User Database”).
For most purposes, it is better to use HOME, precisely because this lets the user specify the value.
This is the name that the user used to log in. Since the value in the environment can be tweaked arbitrarily, this is not a reliable way to identify the user who is running a program; a function like getlogin (the section called “Identifying Who Logged In”) is better for that purpose.
For most purposes, it is better to use LOGNAME, precisely because this lets the user specify the value.
A path is a sequence of directory names which is used for searching for a file. The variable PATH holds a path used for searching for programs to be run.
The execlp and execvp functions (the section called “Executing a File”) use this environment variable, as do many shells and other utilities which are implemented in terms of those functions.
The syntax of a path is a sequence of directory names separated by colons. An empty string instead of a directory name stands for the current directory (the section called “Working Directory”).
A typical value for this environment variable might be a string like:
:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
This means that if the user tries to execute a program named foo, the system will look for files named foo, /bin/foo, /etc/foo, and so on. The first of these files that exists is the one that is executed.
This specifies the kind of terminal that is receiving program output. Some programs can make use of this information to take advantage of special escape sequences or terminal modes supported by particular kinds of terminals. Many programs which use the termcap library () use the TERM environment variable, for example.
This specifies the time zone. the section called “Specifying the Time Zone with TZ”, for information about the format of this string and how it is used.
This specifies the default locale to use for attribute categories where neither LC_ALL nor the specific environment variable for that category is set. Chapter 8, for more information about locales.
If this environment variable is set it overrides the selection for all the locales done using the other LC_* environment variables. The value of the other LC_* environment variables is simply ignored in this case.
This specifies what locale to use for character sets and character classification.
This specifies what locale to use for printing messages and to parse responses.
This specifies what locale to use for formatting monetary values.
This specifies what locale to use for formatting date/time values.
This specifies the directories in which the catopen function looks for message translation catalogs.
If this environment variable is defined, it suppresses the usual reordering of command line arguments by getopt and argp_parse. the section called “Program Argument Syntax Conventions”.