SU(1)                   System General Commands Manual                   SU(1)

NAME
     su - substitute user identity

SYNOPSIS
     su [-flmp] [login [shell arguments]]

DESCRIPTION
     su requests the password for login and switches to that user and group ID
     after validating the password.  A shell is then executed, and any addi-
     tional shell arguments after the login name are passed to the shell.  su
     uses the standard API calls which in turn communicate to the LSASS which
     securely handles access to the user database. The user database may be
     local to the machine or served by Active Directory (AD).  If su is exe-
     cuted by Administrator (local or domain), then no password is requested
     and a shell with the appropriate user ID is executed.  If su is executed
     with no login then it is assumed the user is local administrator.  The
     local administrator is identified by its unique UID of 197108.  This use
     of the UID is the most portable method of correctly choosing the local
     administrator account because "+Administrator" is spelled differently in
     different locales. For systems that have renamed the local administrators
     account this provides that su continues to work correctly also because
     the UID does not change and cannot be assigned to any other account.

     By default, the environment is unmodified with the exception of LOGNAME,
     USER, HOME, and SHELL.  HOME and SHELL are set to the target login's
     default values.  LOGNAME and USER are set to the target login, unless the
     target login has a user ID of Administrator, in which case it is unmodi-
     fied.  The invoked shell is the target login's.  This is the traditional
     behavior of su.

     The options are as follows:

     -f      If the invoked shell is csh(1), this option prevents it from
             reading the ``.cshrc'' file.

     -l      Simulate a full login.  The environment is discarded except for
             HOME, SHELL, PATH, TERM, LOGNAME, and USER.  HOME and SHELL are
             modified as above.  LOGNAME and USER are set to the target login.
             PATH is set to the paths that the target login user would nor-
             mally have set by the system at login.  TERM is imported from
             your current environment.  The invoked shell is the target
             login's, and su will change directory to the target login's home
             directory.

     -m      Leave the environment unmodified.  The invoked shell is your
             login shell, and no directory changes are made.

     -p      Always as for a password for login even when the invoking user is
             an Administrator. This will create a security token with network
             access.

     The -l and -m options are mutually exclusive; the last one specified
     overrides any previous ones.

     If the optional shell arguments are provided on the command line, they
     are passed to the login shell of the target login.  This allows it to
     pass arbitrary commands via the -c option as understood by most shells.
     Note that -c usually expects a single argument only; you have to quote it
     when passing multiple words.

     By default (unless the prompt is reset by a startup file) the superuser
     prompt is set to ``#'' to remind one of its awesome power.

EXAMPLES
     su bin -c makewhatis
            Runs the command makewhatis as user bin.  You will be asked for
            bin's password unless your real UID is either 197108 (local admin-
            istrator) or 1049076 (domain administrator).  Note: the '-c' is an
            option to the shell.

     su bin -c 'makewhatis /usr/local/man'
            Same as above, but the target command consists of more than a sin-
            gle word.  Note: the '-c' is an option to the shell.

     su -l foo
            Pretend a login for user foo.

ENVIRONMENT
     The following environment variables affect the execution of su:

     HOME     Default home directory of real user ID unless modified as speci-
              fied above.

     PATH     Default search path of real user ID unless modified as specified
              above.

     TERM     Provides terminal type which may be retained for the substituted
              user ID.

     LOGNAME  The user ID is always the effective ID (the target user ID)
              after an su unless the user ID is 0 (root).

     USER     Same as LOGNAME.

SEE ALSO
     csh(1), login(1), sh(1), skey(1),

HISTORY
     A su command appeared in Version 7 AT&T UNIX.  This version is adapted
     from the 4.4 BSD version for Interix and does not (and should not) need
     to be installed as setuid/setgid root.

Interix                         January 4, 2005                        Interix