Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1a |
both |
#define _POSIX1_SOURCE 2
#include <env.h>
int clearenv(void);
#include <stdlib.h>
int clearenv(void);
Clears all environment variables from the environment table and frees the associated storage.
clearenv() also resets all behavior modified by z/OS® XL C/C++ specific environment variables back to their defaults. For example, if a binary file was opened, then it would support seeking by byte offsets, regardless of record format. If the file is a Variable Record format MVS™ DASD file, then clearing the environment variable causes seeking by encoded values the next time it is opened.
To avoid infringing on the user's name space, the non-POSIX version of this function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you use LANGLVL(EXTENDED).
To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile with LANGLVL(EXTENDED). When you use LANGLVL(EXTENDED) any relevant information in the header is also exposed.
For details about environment variables, see “Using Environment Variables” in z/OS XL C/C++ Programming Guide.
Special behavior for POSIX C: clearenv() can change the value of the pointer environ. Therefore, a copy of that pointer made before a call to clearenv() may no longer be valid after the call to clearenv().
If successful, clearenv() returns 0.
⁄* CELEBC13
This C⁄MVS example needs to be run with POSIX(ON).
It clears the process environment variable list.
*⁄
#define _POSIX_SOURCE 1
#include <env.h>
#include <stdio.h>
extern char **environ;
int count_env() {
int num;
for (num=0; environ[num] != NULL; num++);
return num;
}
main() {
printf("before clearenv(), there are %d environment variables\n",
count_env());
if (clearenv() != 0)
perror("clearenv() error");
else {
printf("after clearenv(), there are %d environment variables\n",
count_env());
setenv("var1", "value1", 1);
setenv("var-two", "Value Two", 1);
printf("after setenv()'s, there are %d environment variables\n",
count_env());
if (clearenv() != 0)
perror("clearenv() error");
else
printf("after clearenv(), there are %d environment variables\n",
count_env());
}
}
before clearenv(), there are 9 environment variables
after clearenv(), there are 0 environment variables
after setenv()'s, there are 2 environment variables
after clearenv(), there are 0 environment variables
⁄* CELEBC14
This example is for a non-POSIX environment, and thus will work under
C++⁄MVS.
*⁄
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
char *x;
⁄* set 3 environment variables to "Y" *⁄
setenv("_EDC_ANSI_OPEN_DEFAULT","Y",1);
setenv("_EDC_BYTE_SEEK","Y",1);
setenv("_EDC_COMPAT","3",1);
⁄* query the setting of _EDC_BYTE_SEEK *⁄
x = getenv("_EDC_BYTE_SEEK");
if (x != NULL)
printf("_EDC_BYTE_SEEK = %s\n",x);
else
printf("_EDC_BYTE_SEEK is undefined\n");
⁄* clear the environment variable table *⁄
clearenv();
⁄* query the setting of _EDC_BYTE_SEEK *⁄
x = getenv("_EDC_BYTE_SEEK");
if (x != NULL)
printf("_EDC_BYTE_SEEK = %s\n",x);
else
printf("_EDC_BYTE_SEEK is undefined\n");
}
_EDC_BYTE_SEEK = Y
_EDC_BYTE_SEEK is undefined