The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Win32-Env-0.03
River stage zero No dependents
++
/ Win32::Env

NAME

Win32::Env - set and retrieve global system and user environment variables under Win32.

SYNOPSIS

        use Win32::Env;

        # Retrieving value
        my $user_path=GetEnv(ENV_USER, 'PATH');
        print $user_path;

        # Setting new value
        SetEnv(ENV_USER, 'PATH', 'C:\\MyBin');

        # Deleting value
        DelEnv(ENV_USER, 'PATH');

        # Retrieving list of all variables in environment
        my @vars=ListEnv(ENV_USER);
        print(join(', ', @vars));

        # Broadcasting message about our changes
        BroadcastEnv();

NOTES

System and user variables

Just like many Unix shells have global defaults and user profile, Windows store several sets of environment variables. Modifying system's set (see "ENV_SYSTEM") will affect every user on system, while working with user's (see "ENV_USER") will only affect current user.

Fixed and variable length values

While it is impossible to distinguish them by normal means (like %ENV or cmd.exe's set command, variable values could be either fixed length or variable length strings. Fixed length strings should always resolve to same literal value that was assigned to them, while variable length strings may have references to other variables in them that in form of %OTHER_VAR% that should be expanded to values of that variables. Note "should". This expansion is not performed by system automatically, but must be done by program that uses variable.

EXPORT

SetEnv GetEnv DelEnv ListEnv BroadcastEnv ENV_USER ENV_SYSTEM

CONSTANTS

ENV_USER

Used as value for $sys_or_usr argument to indicate that you wish to work with current user's environment.

ENV_SYSTEM

Used as value for $sys_or_usr argument to indicate that you wish to work with system's global environment.

FUNCTIONS

SetEnv($sys_or_usr, $variable, $value[, $expand])

        $success=SetEnv($sys_or_usr, $variable, $value);
        $success=SetEnv($sys_or_usr, $variable, $value, $expand);

Sets variable named $variable in environment selected with $sys_or_usr ("ENV_USER" or "ENV_SYSTEM") to specified $value. Optional $expand set to true or false value specifies if value should be marked as variable length string with expandable references or not. See "Fixed and variable length values" for details. If $expand is not defined SetEnv() will use default Windows behavior - any value that have % in it will be marked as variable length. Returns true on success and false otherwise.

GetEnv($sys_or_usr, $variable)

        $value=GetEnv($sys_or_usr, $variable);
        ($value, $expand)=GetEnv($sys_or_usr, $variable);

Returns pair of value of variable named $variable from environment selected with $sys_or_usr ("ENV_USER" or "ENV_SYSTEM") and true or false value signifying if it is should be expanded or not (see "Fixed and variable length values").

DelEnv($sys_or_usr, $variable)

        DelEnv($sys_or_usr, $variable)

Deletes variable named $variable from environment selected with $sys_or_usr ("ENV_USER" or "ENV_SYSTEM").

ListEnv($sys_or_usr)

        @list_of_variables=ListEnv($sys_or_usr);

Returns list of all variables in environment selected with $sys_or_usr ("ENV_USER" or "ENV_SYSTEM").

InsertPathEnv($sys_or_usr, $variable, $path[, $path_separator])

        $success=InsertPathEnv($sys_or_usr, $variable, $path);
        $success=InsertPathEnv($sys_or_usr, $variable, $path[, $path_separator]);

One of common use of enviroment variables is to store path lists to binary, library and other directories like this. This function allows you to insert a path in such a variable. Typical usage in some kind of installation script could be like this:

        InsertPathEnv(ENV_SYSTEM, PATH => $bindir);
        InsertPathEnv(ENV_SYSTEM, PERL5LIB => $libdir);
        BroadcastEnv();

Path specified with $path will be added to $variable from environment selected with $sys_or_usr ("ENV_USER" or "ENV_SYSTEM"), using $path_separator as separators for elements on parse and inserting. If you do not specify a $path_separator, default system path separator will be detected with Config module. Function returns false on failure, and true on success with true value being one of '1' for successful insert or '2' if specified $path already present in $variable.

BroadcastEnv()

        BroadcastEnv();

Broadcasts system message that environment has changed. This will make system processes responsible for environment aware of change, otherwise your changes will be noticed only on next reboot. Note that most user programs or still won't see changes until next run and neither will their children, as they get environment from their parents. Your changes also will not be available in %ENV to either your process or any processes you spawn. Assign to %ENV yourself in addition to SetEnv() if need it.

AUTHOR

Oleg "Rowaa[SR13]" V. Volkov, <ROWAA@cpan.org>

BUGS

Please report any bugs or feature requests to bug-win32-env at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Win32-Env. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Win32::Env

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2006 Oleg "Rowaa[SR13]" V. Volkov, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.