man3/clearenv.3

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