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  documentation  is no longer being maintained and may
       be inaccurate or incomplete.  The Texinfo documentation is
       now the authoritative source.

       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.