clearenv(3)

1clearenv(3)                Library Functions Manual                clearenv(3)
2
3
4

NAME

6       clearenv - clear the environment
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <stdlib.h>
13
14       int clearenv(void);
15
16   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
17
18       clearenv():
19           /* glibc >= 2.19: */ _DEFAULT_SOURCE
20               || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
21

DESCRIPTION

23       The  clearenv() function clears the environment of all name-value pairs
24       and sets the value of the external variable  environ  to  NULL.   After
25       this  call,  new  variables  can  be  added  to  the  environment using
26       putenv(3) and setenv(3).
27

RETURN VALUE

29       The clearenv() function returns zero on success, and a nonzero value on
30       failure.
31

ATTRIBUTES

33       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
34       tributes(7).
35
36       ┌────────────────────────────────┬───────────────┬─────────────────────┐
37       │Interface                       │ Attribute     │ Value               │
38       ├────────────────────────────────┼───────────────┼─────────────────────┤
39       │clearenv()                      │ Thread safety │ MT-Unsafe const:env │
40       └────────────────────────────────┴───────────────┴─────────────────────┘
41

STANDARDS

43       putenv()
44              POSIX.1-2008.
45
46       clearenv()
47              None.
48

HISTORY

50       putenv()
51              glibc 2.0.  POSIX.1-2001.
52
53       clearenv()
54              glibc 2.0.
55
56       Various UNIX variants (DG/UX, HP-UX, QNX, ...).  POSIX.9 (bindings  for
57       FORTRAN77).   POSIX.1-1996 did not accept clearenv() and putenv(3), but
58       changed its mind and scheduled these functions for some later issue  of
59       this   standard   (see  §B.4.6.1).   However,  POSIX.1-2001  adds  only
60       putenv(3), and rejected clearenv().
61

NOTES

63       On systems where clearenv() is unavailable, the assignment
64
65           environ = NULL;
66
67       will probably do.
68
69       The clearenv() function may be useful  in  security-conscious  applica‐
70       tions  that want to precisely control the environment that is passed to
71       programs executed using exec(3).  The  application  would  do  this  by
72       first clearing the environment and then adding select environment vari‐
73       ables.
74
75       Note that the main effect of clearenv() is to adjust the value  of  the
76       pointer  environ(7);  this  function does not erase the contents of the
77       buffers containing the environment definitions.
78
79       The DG/UX and Tru64 man pages write: If environ has  been  modified  by
80       anything  other than the putenv(3), getenv(3), or clearenv() functions,
81       then clearenv() will return an error and the process  environment  will
82       remain unchanged.
83