Debian Codegraph @

upstream/debian-unstable/man3/clearenv.3

raw
1 '\" t
2 .\" Copyright 2001, John Levon <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH clearenv 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 clearenv \- clear the environment
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdlib.h>
16 .P
17 .B "int clearenv(void);"
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR clearenv ():
26 .nf
27 /* glibc >= 2.19: */ _DEFAULT_SOURCE
28 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
29 .fi
30 .SH DESCRIPTION
31 The
32 .BR clearenv ()
33 function clears the environment of all name-value
34 pairs and sets the value of the external variable
35 .I environ
36 to NULL.
37 After this call, new variables can be added to the environment using
38 .BR putenv (3)
39 and
40 .BR setenv (3).
41 .SH RETURN VALUE
42 The
43 .BR clearenv ()
44 function returns zero on success, and a nonzero
45 value on failure.
46 .\" Most versions of UNIX return -1 on error, or do not even have errors.
47 .\" glibc info and the Watcom C library document "a nonzero value".
48 .SH ATTRIBUTES
49 For an explanation of the terms used in this section, see
50 .BR attributes (7).
51 .TS
52 allbox;
53 lbx lb lb
54 l l l.
55 Interface Attribute Value
56 T{
57 .na
58 .nh
59 .BR clearenv ()
60 T} Thread safety MT-Unsafe const:env
61 .TE
62 .SH STANDARDS
63 .TP
64 .BR putenv ()
65 POSIX.1-2008.
66 .TP
67 .BR clearenv ()
68 None.
69 .SH HISTORY
70 .TP
71 .BR putenv ()
72 glibc 2.0.
73 POSIX.1-2001.
74 .TP
75 .BR clearenv ()
76 glibc 2.0.
77 .P
78 Various UNIX variants (DG/UX, HP-UX, QNX, ...).
79 POSIX.9 (bindings for FORTRAN77).
80 POSIX.1-1996 did not accept
81 .BR clearenv ()
82 and
83 .BR putenv (3),
84 but changed its mind and scheduled these functions for some
85 later issue of this standard (see \[sc]B.4.6.1).
86 However, POSIX.1-2001
87 adds only
88 .BR putenv (3),
89 and rejected
90 .BR clearenv ().
91 .SH NOTES
92 On systems where
93 .BR clearenv ()
94 is unavailable, the assignment
95 .P
96 .in +4n
97 .EX
98 environ = NULL;
99 .EE
100 .in
101 .P
102 will probably do.
103 .P
104 The
105 .BR clearenv ()
106 function may be useful in security-conscious applications that want to
107 precisely control the environment that is passed to programs
108 executed using
109 .BR exec (3).
110 The application would do this by first clearing the environment
111 and then adding select environment variables.
112 .P
113 Note that the main effect of
114 .BR clearenv ()
115 is to adjust the value of the pointer
116 .BR environ (7);
117 this function does not erase the contents of the buffers
118 containing the environment definitions.
119 .P
120 The DG/UX and Tru64 man pages write: If
121 .I environ
122 has been modified by anything other than the
123 .BR putenv (3),
124 .BR getenv (3),
125 or
126 .BR clearenv ()
127 functions, then
128 .BR clearenv ()
129 will return an error and the process environment will remain unchanged.
130 .\" .P
131 .\" HP-UX has a ENOMEM error return.
132 .SH SEE ALSO
133 .BR getenv (3),
134 .BR putenv (3),
135 .BR setenv (3),
136 .BR unsetenv (3),
137 .BR environ (7)