SAS/C Library Reference, Vol. 1

setenv -- Assign Environment Variable

SYNOPSIS

 #include <lclib.h>
 int setenv(const char *name, const char *value);

The synopsis for the POSIX implementation is

 #include <stdlib.h>
 int setenv(const char *name, const char *value)

You should use <stdlib.h> only if an appropriate feature test macro has been defined.

DESCRIPTION

setenv creates an environment variable with a specified name and value, or assigns a new value to an existing environment variable. name and value are specified by the string pointed to by the argument string.

The format of name is

 [[scope]:][[groupname].]varname

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

scope

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

: 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.

RETURN VALUE

setenv returns 0 if it is successful, or - 1 if it is unsuccessful.

CAUTION

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

PORTABILITY

Environment variable scopes and groups are SAS/C extensions and should not be used in portable programs.

USAGE NOTES

The same variable name can be set in each scope. However, setenv always returns the value of shortest duration. For example, if a program scope variable is defined, setenv always returns its value.

EXAMPLE

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

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

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

           /* if environment variable HOME not defined           */
        if (!getenv("HOME")) {
        strcpy(home, "/u/");
        cuserid(home+3);           /* Append userid to directory */
                                   /*  name.                     */
        strlwr(home);              /* Translate to lowercase     */
                                   /*  letters.                  */
        rc = setenv("HOME", home); /* Define HOME.               */
        if (rc != 0) {
           perror("setenv 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);
     exit(rc);
  }

RELATED FUNCTIONS

clearenv, getenv, putenv