Technical Reference: Base Operating System and Extensions , Volume 2

setpenv Subroutine

Syntax

#include <usersec.h>

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.

Parameters

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:

PENV_INIT

The user-state environment is initialized as follows:

AUTHSTATE: Retained from the current environment. If the AUTHSTATE value is not present, it is defaulted to the compat value.
KRB5CCNAME: Retained from the current environment. This value is defined if you authenticated through the Distributed Computing Environment (DCE).
USER: Set to the name specified by the User parameter or to the name corresponding to the current real user ID. The name is shortened to a maximum of 8 characters.
LOGIN: Set to the name specified by the User parameter or to the name corresponding to the current real user ID. If set by the User parameter, this value is the complete login name, which may include a DCE cell name.
LOGNAME: Set to the current system environment variable LOGNAME.
TERM: Retained from the current environment. If the TERM value is not present, it is defaulted to an IBM6155.
SHELL: Set from the initial program defined for the real user ID of the current process. If no program is defined, then the /usr/bin/sh shell is used as the default.
HOME: Set from the home directory defined for the real user ID of the current process. If no home directory is defined, the default is /home/guest.
PATH: Set initially to the value for the PATH value in the /etc/environment file. If not set, it is destructively replaced by the default value of PATH=/usr/bin:$HOME:. (The final period specifies the working directory). The PATH variable is destructively replaced by the usrenv attribute for this user in the /etc/security/environ file if the PATH value exists in the /etc/environment file.

The following files are read for additional environment variables:

/etc/environment: Variables defined in this file are added to the environment.
/etc/security/environ: Environment variables defined for the user in this file are added to the user-state environment.

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:

LOGNAME: Set to the current LOGNAME value in the protected user environment. The login (tsm) command passes this value to the setpenv subroutine to ensure correctness.
NAME: Set to the login name corresponding to the real user ID.
TTY: Set to the TTY name corresponding to standard input.

The following file is read for additional environment variables:

/etc/security/environ: The system-state environment variables defined for the user in this file are added to the environment. The system-state variables in the Environment parameter are added to the environment. These are preceded by the SYSENVIRON keyword.

PENV_DELTA

The existing user-state and system-state environment variables are preserved and the variables defined in the Environment parameter are added.

PENV_RESET

The existing environment is cleared and totally replaced by the content of the Environment parameter.

PENV_KLEEN

Closes all open file descriptors, except 0, 1, and 2, before executing the command. This value must be logically ORed with PENV_DELTA, PENV_RESET, or PENV_INIT. It cannot be used alone.

PENV_NOPROF

The new shell will not be treated as a login shell. Only valid when used with the PENV_INIT flag.

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.

Return Values

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.

Error Codes

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

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.