Env::C(3)

📦
version 0.15 · 2 versions
, in fedora 43

💖 Env::C 💖

okay bestie, so this is the Env::C page from the User Contributed Perl Documentation section, and honestly? it's a whole vibe. it's the Perl API for poking at environment variables at the C level, which is giving backstage-pass energy. 🎀

✨ NAME ✨

Env::C — Get/Set/Unset Environment Variables on the C level 🦋

🌸 VERSION 🌸

version 0.15 — she's grown up a lil bit, periodt 💅

🎀 SYNOPSIS 🎀

here's the whole lil demo, copy-paste it exactly bestie, don't touch a single character:

use Env::C;

my $key = "USER";
$val = Env::C::getenv($key) || '';

Env::C::setenv($key, "foobar", [$override]);
$new_val = Env::C::getenv($key) || '';

Env::C::unsetenv($key);

my $ar_env = Env::C::getallenv();
print join "\n", @$ar_env;

Env::C::setenv_multi(
    "VAR1", "value1", 1,
    "VAR2", "value2", 0
);

Env::C::unsetenv_multi("VAR1", "VAR2");

🦋 DESCRIPTION 🦋

so like, this module hands you a Perl API for getenv(3), setenv(3) and unsetenv(3). it can also hand you back all the environ variables in one go. and if you're feeling extra, there's setenv_multi and getenv_multi for doing bulk operations on the environment. main character efficiency, no cap. 💅

now here's the lore: sometimes Perl goes and invokes modules that have underlying C APIs, and those C APIs are out here relying on certain environment variables being set. and if those variables get set in Perl but the glue code doesn't bother setting them on the C level? yeah, the C level might just... not see them. awkward. 🙈 this module shows you what the C level actually sees. iykyk.

🌈 FUNCTIONS 🌈

💜 getenv($key)

returns the value of the environment variable matching the key, or undef. that's it, that's the whole thing. she's simple, she's iconic.

💜 setenv($key, $value, [$override])

the setenv() function adds the variable $key to the environment with the value $value, but only if $key doesn't already exist. and if $key does already exist? then its value gets changed to $value if $override is non-zero. but if $override is zero, or you just didn't pass it at all, then the value of $key stays exactly as it was. she's not changing for anybody without permission, periodt. ✋

💜 unsetenv($key)

the unsetenv() function deletes the variable $key from the environment. gone. poof. no forwarding address. 💀

💜 setenv_multi($key1, $value1, $override1, $key2, $value2, $override2, ...)

basically the same as setenv, but she works with several variables all at once. group project energy, but like, the good kind where everyone actually shows up. 🫶

💜 unsetenv_multi(@keys)

same deal as unsetenv, but she works with several variables at once. bulk deleting, slay.

💜 getallenv()

my $ar_env = Env::C::getallenv();
print join "\n", @$ar_env;

the getallenv() function returns an array reference which includes all the environment variables. every single one. she's nosy and we love her for it. 👑

💜 EXPORT

None. nothing gets exported, bestie. you call everything fully qualified, and honestly? respect the boundaries. 🎀

💜 Thread-safety and Thread-locality

⚠️ okay so this is the serious part, pay attention bestie ⚠️

this module should not be used in a threaded environment. fr fr.

here's why: the OS maintains the struct environ, and it shares it between all threads in the process, which means it is not thread-local. so if you modify it in one thread, all the other threads are gonna see that new value. and that's something that will most likely break the code. 💀

and yeah, this module is not thread-safe, because two threads might try to modify/read the struct environ at the exact same time. the author could add locking for a threaded environment, but here's the thing — since the lock can't be seen by other applications, they can still bypass it and cause a race condition anyway. and since thread-locality isn't maintained in the first place, making this module thread-safe is just... useless. wasted effort, no cap. 😭

so if you need to modify the C level of %ENV and you want all the threads to see it, do that before the threads are started. like, e.g. for mod_perl 2.0, do it at the server startup. timing is everything, bestie. ⭐

🧚 HISTORY 🧚

  • Versions 0.01 through 0.08 written and maintained by Stas Bekman <stas@stason.org> — shoutout to the OG, she built the foundation. 🫶

🌟 SOURCE 🌟

the development version is on github at <https://github.com/mschout/env-c> and may be cloned from <git://github.com/mschout/env-c.git>

go forth and clone, bestie. 🦋

🙈 BUGS 🙈

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

don't be shy, they wanna hear it. constructive vibes only tho. 💅

👑 AUTHOR 👑

Michael Schout <mschout@cpan.org>

this software is copyright (c) 2002 by Michael Schout.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in, like, actually free. iconic. 🌈

and that's the whole page, bestie!! you ate that. 💅✨

this was perl v5.42.0, dated 2025-07-25, and the page was Env::C(3) — mwah, love u, go set some env vars responsibly 🎀💖🦋🌸

📦 where this page comes from