.TH setuid() "" "" "System Call (libc)"
.PC "Set user identifier"
.B "#include <unistd.h>"
\fBint setuid(\fIid\^\fB)\fR
\fBint \fIid\^\fB;\fR
.PP
.II "user identifier^definition"
The
.I "user identifier"
is the number that identifies the user who ``owns'' a given file.
The suite of users is defined in file
.BR /etc/passwd .
When a file is executable, the executing process inherits its user identifier
(and thus, its user-level permissions) from the file where it lives on disk.
The user identifier comes in three forms:
.IP \fBreal\fR
This is the identifier of the user who is running the process.
.IP \fBeffective\fR
This is the user identifier that determines the access rights of the process.
These rights are the same as those of the real user identifier unless they
have been altered by executing a file whose
.B setuid
bit is set.
.IP "\fBsaved effective\fR"
This permits a process to step back and forth between its real and effective
user identifiers.
If you return from an effective user identifier
to your real one, the previously effective id is saved so you can revert
to it if need be.
.PP
The system call
.B setuid()
lets you alter the real and effective user identifiers of the calling
process to the user identifier
.IR uid .
The behavior of
.B setuid()
varies depending upon the following:
.IP \fB1.\fR 0.3i
If the effective user identifier is that of the superuser,
.B setuid()
sets the real, effective, and saved effective user identifiers to
.IR uid .
.IP \fB2.\fR
If the real user identifier is the same as
.IR uid ,
.B setuid()
sets the effective user identifier to
.IR uid .
.IP \fB3.\fR
If the saved effective user identifier is same as
.IR uid ,
.B setuid()
sets the effective user identifier to
.IR uid .
.PP
To
.B setuid
an existing executable file, use the command
.BR chmod .
.SH "See Also"
.Xr "chmod," chmod.c
.Xr "execution," execution
.Xr "getuid()," getuid
.Xr "libc," libc
.Xr "login," login
.Xr "setgid()," setgid
.Xr "unistd.h" unistd.h
.br
\*(PX Standard, \(sc4.2.2
.SH Diagnostics
.B setuid()
returns zero on success, or \-1 on failure.
.SH Notes
For more information on the user id, see the Lexicon entry for
.BR execution .
