.TH setgid() "" "" "System Call (libc)"
.PC "Set group id and user id"
.B "#include <unistd.h>"
\fBint setgid(\fIid\^\fB) int \fIid\^\fB;\fR
.PP
.II "group identifier^definition"
The
.I "group identifier"
is the number that identifies the user group that ``owns'' a given file.
File
.B /etc/group
establishes the set of groups that your \*(CO system recognizes.
(For details on how this file is laid out, see the Lexicon entry for
.BR group ).
When a file is executable, the executing process inherits its group identifier
(and thus, its group-level permissions) from the file
in which it resides on disk.
For example, the program
.B troff
resides in file
.BR /bin/troff .
This file is ``owned'' by group
.BR bin ;
thus, when you execute
.BR troff ,
its group-level permissions are those of group
.BR bin .
.PP
The group identifier comes in three forms:
.IP \fBreal\fR
This is the group identifier of the user who is running the process.
.IP \fBeffective\fR
This is the group identifier that determines the access rights of the
process.
These rights are the same as those of the real group identifier unless they
have been altered by executing a file whose
.B setgid
bit is set.
For example, the program
.B troff
does
.I not
have the setgid bit set; thus, when you execute
.BR troff ,
the group permissions of the
.B troff
process remain those of your group, not those of the group
.BR bin .
On the other hand, the program
.B /usr/lib/uucp/uucico
does have the setgid bit set; thus, when you invoke
.BR uucico ,
the
.B uucico
process uses the permissions of
.BR uucico 's
group (that is, of group \fBuucp\fR), instead of your group.
.IP "\fBsaved effective\fR"
This permits a process to step back and forth between its real and effective
group identifiers.
If you return from an effective group identifier
to your real one, the system saves the previously effective identifier
so you can revert to it if need be.
.PP
The system call
.B setgid()
lets you set the real and effective group identifiers of the calling
process to the group identifier
.IR gid .
The behavior of
.B setgid()
varies depending upon the following:
.IP \fB1.\fR 0.3i
If
.B setgid()
is invoked by a user whose effective user identifier is that of the superuser
.BR root ,
.B setgid()
sets the real, effective, and saved effective group identifiers to
.IR gid .
.IP \fB2.\fR
If
.B setgid()
is invoked by a user whose real group identifier is the same as
.IR gid ,
.B setgid()
sets the effective group identifier to
.IR gid .
.IP \fB3.\fR
If
.B setgid()
is invoked by a user whose saved effective group identifier is same as
.IR gid ,
.B setgid()
sets the effective group identifier to
.IR gid .
.PP
If all goes well,
.B setgid()
returns zero.
If a problem arises, it returns \-1.
.SH "See Also"
.Xr "execution," execution
.Xr "getuid()," getuid
.Xr "libc," libc
.Xr "login," login
.Xr "setuid()," setuid
.Xr "unistd.h" unistd.h
.br
\*(PX Standard, \(sc4.2.2
