Hamilton LaboratoriesHamilton C shell 2012User guideExternal utilities

su

Oregon Coast

su
Previous | Next

        su:  Run an elevated command or as another user

Usage:  su.exe [-.eCLnPStvxwh-] [-c <colors>]
      [-o <options>] [-p <password>] [-s <setrows> ]
      [-X <errlimit>] [ userid [ command ]]

   su is the Windows equivalent of the UNIX "super user"
   command.  su runs the specified command (by default, the
   C shell) as either an elevated command or as another user
   (or both) in a new window.  By default, it then exits
   immediately.

   Invoked without any command line arguments, su defaults to
   starting an elevated copy of the C shell.

   Even though the command will run with new credentials,
   it will inherit the parent's environment variables and
   current directories. su does this by spawning a copy of
   itself with the new credentials to actually run the command
   and handshaking with it through shared memory to pass the
   environment.

   To run as another user, su uses the Secondary Logon
   service to start that copy of itself meaning that
   system service must be running.

   To elevate, su uses a special copy of itself, elevate.exe,
   which has been marked for the operating system as
   requiring elevation, causing the secure desktop prompt.

   To run elevated as another user, su first spawns a copy
   of itself as the new user, then elevates.

   The userid may be specified as either a simple name or as a
   domain\name pair.  If no userid is specified, or if "."
   is specified, su will interpret that to mean the current
   userid.  If the current user is specified, a password is not
   required because su will already be running as that user.
   (In fact, if a password is specified, seemingly for the
   current user, that's treated as an error to avoid
   accidentally running elevated when that was not the intent.)

   For userids other than the current user, if no password is
   given, su will try logging in without a password.  If that
   fails, su will prompt for a password; the password will not
   be echoed to the screen.

   The command can refer to any executable file or to a C shell
   command or alias.  If a complete path is not specified, su
   will look through the search path.  If an extension is not
   specified, su will try all the usual possibilities:  .csh,
   .exe, .com, .cmd and .bat.  If a corresponding executable
   file cannot be found, su will assume the command is an
   internal C shell command or alias.  If no command is
   specified, su will run the C shell.

   Net use drives are inherited only when elevating, not when
   running as a different user.  Any current directory settings
   in the inherited environment that refer to drives that don't
   exist under the new credentials are silently ignored.
   
   su will not run under Windows 9x and requests to elevate
   are ignored unless running under Vista, Windows 7 or later.

Options:

   -.             Elevate option.  Run the command elevated as the
                  current userid.  No userid or password should
                  be specified.
   -e             Elevate.  Run the command elevated as the
                  specified user.
   -c <colors>    If su is running in a new window because of
                  elevation, use the screen colors specified
                  in the next word, overriding whatever is
                  specified in the COLORS environment variable.
                  If there is neither a COLORS environment nor
                  a -c option specifying the colors, the default
                  is "white on blue".
   -C             Start up a copy of C shell to run the command.
   -L             If the C shell is run, make it a login shell.
   -n             Non-interactive.  The password, if not null,
                  must be passed on the command line.  su will
                  not prompt for it.
   -o <options>   Options to be passed to the C shell, if su
                  calls it.
   -p <password>  Password to be used with the specified userid.
   -P             Pause always.  Prompt for the user to press
                  Enter before exiting.  Implies -w.
   -s <setrows>   If su is running in a new window because of
                  elevation, set the window and buffer sizes
                  to the values specified in the next argument
                  word.  The format is the same as used by the
                  setrows command.  The default, "1000 80 40 80",
                  means a buffer of 1000 rows x 80 columns and
                  a display window of 40 rows x 80 columns.
   -S             Inverse of -L.  If the C shell is run, do
                  not make it a login shell.  Let it run
                  startup.csh only.
   -t             Trace mode.  The command line is written to
                  stderr just prior to invocation.
   -v             Verbose.  If either su or the child exits
                  with a return code greater than the error
                  limit, print the return code and the
                  corresponding system error message.
   -w             Wait for the child to exit before returning,
                  even if it's running in a new window.
   -x             Exit always.  By default, if su is running
                  in a new window because of elevation, it
                  pauses and prompts for the user to press Enter
                  if it writes any messages or if a child exits
                  with an error to ensure the user gets to read
                  what's displayed before the window goes away.
                  This option overrides that default behavior.
   -X <errlimit>  Error limit.  If a child command exits with
                  a return code greater than the specified
                  <errlimit>, su will consider that to be an
                  error.  By default, any return code > 1 is
                  considered an error.

   -h             Help.  (This screen.)
   --             End of options.

Previous | Next