putenv()--Change or Add Environment Variable

 #include <stdlib.h>

 int putenv(const char *string);;  

The putenv() function sets the value of a job-level environment variable by changing an existing variable or creating a new one. The string parameter points to a string of the form name=value, where name is the environment variable and value is the new value for it.

The name cannot contain a blank. For example,

   PATH NAME=/my_lib/joe_user

is not valid because of the blank between PATH and NAME. The name can contain an equal (=) symbol, but the system interprets all characters following the first equal symbol as being the value of the environment variable. For example,

   PATH=NAME=/my_lib/joe_user

will result in a value of 'NAME=/my_lib/joe_user' for the variable PATH.

Authorities and Locks

None.

Parameters

string

(Input) A pointer to the name=value string.

Return Value

Error Conditions

If putenv() is not successful, errno indicates one of the following errors.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

[EFAULT]

The address used for an argument is not correct. In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct. A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL. For example, the string may not be in the correct format.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function. (There is a limit of 4095 environment variables per job.)

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Usage Notes

1. Although putenv() is threadsafe, if a thread calls an environment variable function while another thread is accessing an environment variable from the environ array the thread may see undefined results. The environ array can be accessed directly or by using a pointer returned from the getenv() or Qp0zGetEnv() functions. The environment contents are only protected during calls to the environment variable functions.
   
2. All environment variables are stored with an associated CCSID (coded character set identifier). Because putenv() does not specify a CCSID, the default CCSID for the job is used as the CCSID associated with strings that are stored using putenv().
   
3. No translation is done based on the CCSID. The CCSID is just stored and retrieved as an integer value associated with each environment variable.

Related Information

• getenv()--Get Value of Environment Variable
• Qp0zDltEnv()--Delete an Environment Variable
• Qp0zDltSysEnv()--Delete a System-Level Environment Variable
• Qp0zGetAllSysEnv()--Get All System-Level Environment Variables
• Qp0zGetEnv()--Get Value of Environment Variable (Extended)
• Qp0zGetSysEnv()--Get Value of System-Level Environment Variable
• Qp0zInitEnv()--Initialize Environment for Variables
• Qp0zPutEnv()--Change or Add Environment Variable (Extended)
• Qp0zPutSysEnv()--Change or Add a System-Level Environment

Example

See Code disclaimer information for information pertaining to code examples.

The following example uses putenv() and getenv().

#include <stdio.h>
#include <errno.h>
#include <stdlib.h>

int main(int argc, char **argv)
{
 char     *var1  = "PATH=/:/home/userid";
 char     *name1 = "PATH";
 char     *val1  = NULL;
 int      rc;

 rc = putenv(var1);
 if (rc < 0) {
   printf("Error inserting <%s> in environ, errno = %d\n",
           var1, errno);
   return 1;
 }

 printf("<%s> inserted in environ\n", var1);
 val1 = getenv(name1);
 if (val1 == NULL) {
   printf("Error retrieving <%s> from environ, errno = %d\n",
           name1, errno);
   return 1;
 }

 printf("<%s> retrieved from environ, value is <%s>\n",
         name1, val1);
 return 0;
}

Output:

 <PATH=/:/home/userid> inserted in environ
 <PATH> retrieved from environ, value is </:/home/userid>

For other examples, see the following:

• Using Environment Variables.
  
• Using the Spawn Process and Wait for Child Process APIs.
  
• Using the Spawn Process (using NLS-enabled path name)