NAME

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

VERSION

version 0.15

SYNOPSIS

  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

This module provides a Perl API for getenv(3), setenv(3) and unsetenv(3). It also can return all the environ variables. You also can use setenv_multi and getenv_multi for bulk operations with environment.

Sometimes Perl invokes modules with underlaying C APIs which rely on certain environment variables to be set. If these variables are set in Perl and the glue code doesn't worry to set them on the C level, these variables might not be seen by the C level. This module shows what really the C level sees.

FUNCTIONS

getenv($key)

Returns the value of the environment variable matching the key or undef.

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

The setenv() function adds the variable $key to the environment with the value $value, if $key does not already exist. If $key does exist in the environment, then its value is changed to $value if $override is non-zero; if $override is zero or is not passed, then the value of $key is not changed.

unsetenv($key)

The unsetenv() function deletes the variable $key from the environment.

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

Similar to setenv, but works with several variables at once.

unsetenv_multi(@keys)

Similar to unsetenv, but works with several variables at once.

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.

EXPORT

None.

Thread-safety and Thread-locality

This module should not be used in a threaded enviroment.

The OS, which maintains the struct environ, shares it between all threads in the process, which means it is not thread-local. So if you modify it in one thread, all other threads will see the new value. Something that will most likely break the code.

This module is not thread-safe, since two threads may attempt to modify/read the struct environ at the same time. I could add locking if in a threaded environment. However since the lock can't be seen by other applications, they can still bypass it causing race condition. But since thread-locality is not maintained, making this module thread-safe is useless.

If you need to modify the C level of %ENV for all threads to see, do that before threads are started. (e.g. for mod_perl 2.0, at the server startup).

HISTORY

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

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

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

AUTHOR

Michael Schout <mschout@cpan.org>

COPYRIGHT AND LICENSE

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.