NAME

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

VERSION

version 0.13

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;

DESCRIPTION

This module provides a Perl API for getenv(3), setenv(3) and unsetenv(3). It also can return all the environ variables.

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.

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 the threaded enviroment.

Thread-locality: the OS, which maintains the struct environ, shares it between all threads in the process. 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 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 http://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.

cpanm Env::C

perl -MCPAN -e shell
install Env::C