setuid()

Set the real, effective and saved user IDs

Synopsis:

#include <unistd.h>

int setuid( uid_t uid );

Library:

libc

Description:

The setuid() function allows the calling process to set the real, effective and saved user IDs based on the following:

• If the process isn't the superuser, setuid() sets the real user ID, effective user ID and saved user ID to uid.
• If the process isn't the superuser, but uid is equal to the real user ID or saved set-user ID, setuid() sets the effective user ID to uid; the real and saved user IDs aren't changed.

If a set-UID process sets its effective user ID to its real user ID, it can still set its effective user ID back to the saved set-UID.

If you wish to change only the effective user ID, even if you have appropriate privileges, you should consider using the seteuid() function.

The "superuser" is defined as any process with an effective user ID of 0, or an effective user ID of root.

Returns:

0 for success, or -1 if an error occurs (errno is set).

Errors:

EINVAL

The value of uid is out of range.

EPERM

The process isn't the superuser, and uid doesn't match the real user ID or saved set-user ID.

Examples:

/*
 * This process sets its userid to 0 (root)
 */
#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>

int main( void )
{
    uid_t ouid;

    ouid = getuid();
    if( setuid( 0 ) == -1 ) {
        perror( "setuid" );
        return EXIT_FAILURE;
    }

    printf( "userid %d switched to 0\n", ouid );
    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1

See also:

errno, setegid(), seteuid(), setgid()