putenv

putenv

Modify or Define Environment Variable

Portability: UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
PORTABILITY
USAGE NOTES
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <lclib.h>

int putenv(const char *string);

DESCRIPTION

The putenv function creates an environment variable with a specified name and value, or replaces an existing environment variable with a new value. The name and value are specified by the string pointed to by the argument string . For example,

[[scope]:] [groupname].]varname[=value]

For portable use, the scope and groupname parts of the string must be omitted, and a value must be present. The parts are

scope

specifies the scope at which the environment variable is to be added or modified. It may be specified as one of the following:

	PRogram
	External (or STorage)
	PErmanent (or Lasting)
	SEssion.

scope is not case sensitive. The uppercase letters indicate the minimum abbreviation that may be specified for the scope name. See Environment Variables for a definition of the environment-variable scopes. The SEssion scope is CMS specific and refers to GLOBALV SESSION variables. For all other systems, a SEssion-scope specification is treated as if it were an External-scope specification. If you do not specify scope, PRogram scope is assumed. Scopes other than PRogram are valid only under TSO, CMS, and CICS.

groupname

specifies an optional group name for the environment variable. groupname is only meaningful for nonprogram-scope variables. If a program-scope, environment-variable name appears to have a group name, the group name is simply treated as part of the variable name. See Environment Variables for more information.

varname

specifies the name of the environment variable. For nonprogram-scope variables, some environments restrict the size of the variable name. In these environments, the name is truncated, if necessary.

=value

specifies the value to be assigned to the environment variable. If no value is present, a 0-length string "" is assumed. For nonprogram-scope variables, the value is truncated if it is longer than supported for that scope.

RETURN VALUE

putenv returns 0 if successful or -1 if unsuccessful.

CAUTION

Do not modify the environment by changing the external variable environ or the data it points to in a program that uses putenv . The putenv function may cause the value of environ to change.

PORTABILITY

putenv is defined by many UNIX and MS-DOS C compilers. Scopes and groups for environment variables are SAS/C extensions.

USAGE NOTES

You can define the same variable name in more than one scope. However, getenv always returns the value of shortest duration. For example, if a program-scope variable is defined, getenv always returns its value.

EXAMPLE

This example creates an environment variable named HOME , if it does not already exist, and then invokes an USS shell command:

#include <stdio.h>
#include <lclib.h>
#include <lcstring.h>

main()
{
   char home[17]
   char cmd[300]
   int rc;

      /* if environment variable HOME not defined                */
   if (!getenv("HOME")) {
      strcpy(home, "HOME=/u/");
      cuserid(home+8);      /* Append userid to directory name.  */
      strlwr(home);         /* Translate to lowercase letters.   */
      rc = putenv(home);    /* Define HOME environment variable. */
      if (rc !=0) {
         perror("putenv failure");
         exit(EXIT_FAILURE);
      }
   }
   puts("Enter shell command");
   memcpy(cmd, "//sh:", 5); /* prefix for system function        */
   gets(cmd+5);
   rc = system(cmd);        /* Invoke the shell command.         */
   printf("shell command status code was %d.n", rc);
}

RELATED FUNCTIONS

clearenv , getenv , setenv