setuser(2)                                                   setuser(2)

  setuser

  NAME

    setuser() - change effective and real uid and gid of process

  SYNOPSIS

    #include 

    int setuser(char *username, char *password, int flags)

  DESCRIPTION

    The setuser(2) function changes the effective and real uid and gid of the
    current process to that of the specified username. All of the security
    attributes and permissions become those of username. However, the process'
    current working directory does not change.

    The setuser(2) function takes the following arguments:

    username
        The name of the user.

    password
        The plaintext password for the specified username. The password is not
        needed if the security ID of the calling process is one of SYSTEM,
        local+Administrator (where local is the name of the local domain), or
        pdomain+Administrator (where pdomain is the name of the principal
        domain). In this case, password can be passed as the NULL pointer.

    flags
        Control flags. These possible values for flags are defined in
        :

        SU_COMPLETE
            Change the real and effective user and group IDs and all security
            attributes to the default for the specified user.

        SU_CHECK
            Check that the process will be able to perform a setuser(2) action
            using SU_COMPLETE for the specified username and password. This is
            a quick way to verify a password for a user. This action is
            equivalent to the older INTERIX call, authenticateuser(2).

    There can be a performance degradation if a process changes identity to a
    user who does not have permission to be located in the current working
    directory. The best solution is, after a call to setuser(2), call chdir(2)
    to set the working directory to a directory known to be permitted for the
    new identity.

    You must have the right to log on interactively on a domain controller for
    someone to call setuser(2) for you. An administrator, however, can call
    setuser(2) for you even if you do not have the right to log on
    interactively to a domain controller. If the administrator calls
    setuser(2) for you, he or she is not required to use your password.

  RETURN VALUE

    On success, the setuser(2) function returns 0. On failure, it returns -
    1 and sets errno.

  ERRORS

    The setuser(2) function can fail for the following reasons:

    [ENOMEM]
        Not enough memory to complete the request.

    [EINVAL]
        An argument is invalid or is missing.

    [EPERM]
        The requesting process does not have permission to change to the new
        user. Either or both of the username or password were incorrectly
        specified.

  NOTES

    This function replaces authenticateuser(2). In fact, the version of
    authenticateuser(2) in this release is a wrapper around setuser(2).

  SEE ALSO

    setuid(2)

    setgid(2)

    exec_asuser(2)

    authenticateuser(2)

  USAGE NOTES

    The setuser function is thread safe.

    The setuser function is not async-signal safe.