[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

setpenv Subroutine

Purpose

Sets the current process environment.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int setpenv ( User,  Mode,  Environment,  Command)
char *User;
int Mode;
char **Environment;
char *Command;

Description

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 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.

[ Previous | Next | Contents | Glossary | Home | Search ]