Sets the current process environment.
int setpenv (
User,
Mode,
Environment,
Command)
char *User;
int Mode;
char **Environment;
char *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. |
Command | Specifies the command to be executed. If the Mode parameter contains the PENV_ARGV value, then the Command parameter is assumed to be a valid argument vector for the execv subroutine. |
Environment | Specifies the value of user-state and system-state environment variables in the same format returned by the getpenv subroutine. The user-state variables are prefaced by the keyword USRENVIRON:, and the system-state variables are prefaced by the keyword SYSENVIRON:. Each variable is defined by a string of the form var=value, which is an array of null-terminated character pointers. |
Mode | Specifies how the setpenv subroutine is to set the environment and run the command. This parameter is a bit mask and must contain only one of the following values, which are defined in the usersec.h file: |
For both system-state and user-state environments, variable substitution is performed.
The Mode parameter may also contain:
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 subroutine.
The login command, su command.
List of Security and Auditing Subroutines, Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.