1Env::C(3)             User Contributed Perl Documentation            Env::C(3)
2
3
4

NAME

6       Env::C - Get/Set/Unset Environment Variables on the C level
7

VERSION

9       version 0.15
10

SYNOPSIS

12         use Env::C;
13
14         my $key = "USER";
15         $val = Env::C::getenv($key) || '';
16
17         Env::C::setenv($key, "foobar", [$override]);
18         $new_val = Env::C::getenv($key) || '';
19
20         Env::C::unsetenv($key);
21
22         my $ar_env = Env::C::getallenv();
23         print join "\n", @$ar_env;
24
25         Env::C::setenv_multi(
26             "VAR1", "value1", 1,
27             "VAR2", "value2", 0
28         );
29
30         Env::C::unsetenv_multi("VAR1", "VAR2");
31

DESCRIPTION

33       This module provides a Perl API for getenv(3), setenv(3) and
34       unsetenv(3). It also can return all the "environ" variables.  You also
35       can use "setenv_multi" and "getenv_multi" for bulk operations with
36       environment.
37
38       Sometimes Perl invokes modules with underlaying C APIs which rely on
39       certain environment variables to be set. If these variables are set in
40       Perl and the glue code doesn't worry to set them on the C level, these
41       variables might not be seen by the C level. This module shows what
42       really the C level sees.
43

FUNCTIONS

45   getenv($key)
46       Returns the value of the environment variable matching the key or
47       "undef".
48
49   setenv($key, $value, [$override])
50       The setenv() function adds the variable $key to the environment with
51       the value $value, if $key does not already exist. If $key does exist in
52       the environment, then its value is changed to $value if $override is
53       non-zero; if $override is zero or is not passed, then the value of $key
54       is not changed.
55
56   unsetenv($key)
57       The unsetenv() function deletes the variable $key from the environment.
58
59   setenv_multi($key1, $value1, $override1, $key2, $value2, $override2, ...)
60       Similar to "setenv", but works with several variables at once.
61
62   unsetenv_multi(@keys)
63       Similar to "unsetenv", but works with several variables at once.
64
65   getallenv()
66         my $ar_env = Env::C::getallenv();
67         print join "\n", @$ar_env;
68
69       The getallenv() function returns an array reference which includes all
70       the environment variables.
71
72   EXPORT
73       None.
74

Thread-safety and Thread-locality

76       This module should not be used in a threaded enviroment.
77
78       The OS, which maintains the struct "environ", shares it between all
79       threads in the process, which means it is not thread-local. So if you
80       modify it in one thread, all other threads will see the new value.
81       Something that will most likely break the code.
82
83       This module is not thread-safe, since two threads may attempt to
84       modify/read the struct "environ" at the same time. I could add locking
85       if in a threaded environment. However since the lock can't be seen by
86       other applications, they can still bypass it causing race condition.
87       But since thread-locality is not maintained, making this module thread-
88       safe is useless.
89
90       If you need to modify the C level of %ENV for all threads to see, do
91       that before threads are started. (e.g. for mod_perl 2.0, at the server
92       startup).
93

HISTORY

95       •   Versions 0.01 through 0.08 written and maintained by Stas Bekman
96           <stas@stason.org>
97

SOURCE

99       The development version is on github at
100       <https://github.com/mschout/env-c> and may be cloned from
101       <git://github.com/mschout/env-c.git>
102

BUGS

104       Please report any bugs or feature requests to bug-env-c@rt.cpan.org or
105       through the web interface at:
106        http://rt.cpan.org/Public/Dist/Display.html?Name=Env-C
107

AUTHOR

109       Michael Schout <mschout@cpan.org>
110

112       This software is copyright (c) 2002 by Michael Schout.
113
114       This is free software; you can redistribute it and/or modify it under
115       the same terms as the Perl 5 programming language system itself.
116
117
118
119perl v5.38.0                      2023-07-20                         Env::C(3)
Impressum