Sets the current process environment.
Security Library (libc.a)
int setpenv ( User, Mode, Environment, Command)
The setpenv subroutine first sets the environment of the current process according to its parameter values, and then sets the working directory and runs a specified command. If the User parameter is specified, the process environment is set to that of the specified user, the user's working directory is set, and the specified command run. If the User parameter is not specified, then the environment and working directory are set to that of the current process, and the command is run from this process. The environment consists of both user-state and system-state environment variables.
Note: The setpenv subroutine requires the setpcred subroutine to precede it.
The setpenv subroutine
performs the following steps:
|Setting the Process Environment||The first step involves changing the user-state and system-state environment. Since this is dependent on the values of the Mode and Environment parameters, see the description for the Mode parameter for more information.|
|Setting the Process Current Working Directory|
|After the user-state and system-state environment is set, the working directory of the process may be set. If the Mode parameter includes the PENV_INIT value, the current working directory is changed to the user's initial login directory (defined in the /etc/passwd file). Otherwise, the current working directory is unchanged.|
|Executing the Initial Program||After the working directory of the process is reset, the initial program
(usually the shell interpreter) is executed. If the Command
parameter is null, the shell from the user database is used. If the
parameter is not defined, the shell from the user-state environment is used
and the Command parameter defaults to the /usr/bin/sh
file. If the Command parameter is not null, it specifies the
command to be executed. If the Mode parameter contains the
PENV_ARGV value, the Command parameter is assumed to be
in the argv structure and is passed to the execve subroutine. The string contained in
the Command parameter is used as the Path parameter of
the execve subroutine. If the Mode parameter does
not contain PENV_ARGV value, the Command parameter is
parsed into an argv structure and executed. If the
Command parameter contains the $SHELL value,
substitution is done prior to execution.
Note: This step will fail if the Command parameter contains the $SHELL value but the user-state environment does not contain the SHELL value.
The following files are read for additional environment variables:
The user-state variables in the Environment parameter are added to the user-state environment. These are preceded by the USRENVIRON: keyword.
The system-state environment is initialized as follows:
The following file is read for additional environment variables:
For both system-state and user-state environments, variable substitution is performed.
The Mode parameter may also
|PENV_ARGV||Specifies that the Command parameter is already in argv format and need not be parsed. This value must be logically ORed with PENV_DELTA, PENV_RESET, or PENV_INIT. It cannot be used alone.|
|User||Specifies the user name whose environment and working directory is to be set and the specified command run. If a null pointer is given, the current real uid is used to determine the name of the user.|
If the environment was successfully established, this function does not return. If the setpenv subroutine fails, a value of -1 is returned and the errno global variable is set to indicate the error.
The setpenv subroutine
fails if one or more of the following are true:
|EINVAL||The Mode parameter contains values other than PENV_INIT, PENV_DELTA, PENV_RESET, or PENV_ARGV.|
|EINVAL||The Mode parameter contains more than one of PENV_INIT, PENV_DELTA, or PENV_RESET values.|
|EINVAL||The Environment parameter is neither null nor empty, and does not contain a valid environment string.|
|EPERM||The caller does not have read access to the environment defined for the system, or the user does not have permission to change the specified attributes.|
Other errors may be set by subroutines invoked by the setpenv subroutine.
This subroutine is part of Base Operating System (BOS) Runtime.
The execl, execv, execle, execve, execlp, execvp, or exect subroutine, getpenv subroutine, setpcred (setpcred Subroutine) subroutine.
The login command, su command.
List of Security and Auditing Subroutines, Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.