[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Base Operating System and Extensions, 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.
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.2 General Programming Concepts: Writing and Debugging Programs.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]