SU(1)                                                       SU(1)

NAME
       su - run a shell with substitute user and group IDs

SYNOPSIS
       su  [-flmp]  [-c  command]  [-s  shell] [--login] [--fast]
       [--preserve-environment]               [--command=command]
       [--shell=shell] [-] [--help] [--version] [user [arg...]]

DESCRIPTION
       This  manual  page  documents  the  GNU version of su.  su
       allows one user to temporarily become  another  user.   It
       runs  a  shell  with the real and effective user ID, group
       ID, and supplemental groups of USER.  If no USER is given,
       the  default  is  root,  the super-user.  The shell run is
       taken from USER's password entry, or /bin/sh  if  none  is
       specified  there.   If USER has a password, su prompts for
       the password unless run by a user with real user ID 0 (the
       super-user).

       By  default, su does not change the current directory.  It
       sets the environment variables `HOME' and `SHELL' from the
       password  entry  for  USER,  and if USER is not the super-
       user, sets `USER' and `LOGNAME' to USER.  By default,  the
       shell is not a login shell.

       If  one  or  more ARGs are given, they are passed as addi-
       tional arguments to the shell.

       su does not handle /bin/sh or other shells specially (set-
       ting  argv[0] to "-su", passing -c only to certain shells,
       etc.).

       On systems that have syslog, su can be compiled to  report
       failed,  and optionally successful, su attempts using sys-
       log.

   OPTIONS
       -c COMMAND, --command=COMMAND
              Pass COMMAND, a single command line to run, to  the
              shell  with  a  -c  option  instead  of starting an
              interactive shell.

       -f, --fast
              Pass the -f option to  the  shell.   This  probably
              only  makes  sense with csh and tcsh, for which the
              -f  option  prevents  reading  the   startup   file
              (.cshrc).   With  Bourne-like shells, the -f option
              disables filename pattern expansion, which is not a
              generally desirable thing to do.

       --help Print  a  usage message on standard output and exit
              successfully.

       -, -l, --login
              Make the shell a login shell.  This means the  fol-
              lowing.   Unset  all  environment  variables except
              `TERM', `HOME',  and  `SHELL'  (which  are  set  as
              described  above),  and `USER' and `LOGNAME' (which
              are set, even  for  the  super-user,  as  described
              above),  and  set  `PATH'  to a compiled-in default
              value.  Change to USER's home  directory.   Prepend
              "-"  to the shell's name, to make it read its login
              startup file(s).

       -m, -p, --preserve-environment
              Do not change  the  environment  variables  `HOME',
              `USER', `LOGNAME', or `SHELL'.  Run the shell given
              in the  environment  variable  `SHELL'  instead  of
              USER's shell from /etc/passwd, unless the user run-
              ning su is not the superuser and  USER's  shell  is
              restricted.   A restricted shell is one that is not
              listed in the file /etc/shells, or in a compiled-in
              list  if  that  file does not exist.  Parts of what
              this option does can be overridden by  --login  and
              --shell.

       -s, --shell shell
              Run SHELL instead of USER's shell from /etc/passwd,
              unless the user running su is not the superuser and
              USER's shell is restricted.

       --version
              Print  version  information on standard output then
              exit successfully.

FSF                    GNU Shell Utilities                      1