lib/libc/sys/setregid.2

   1 .\"     $NetBSD: setregid.2,v 1.23 2008/05/02 18:11:05 martin Exp $
   2 .\"
   3 .\" Copyright (c) 1998, 2000, 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Charles M. Hannum.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\"
  31 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
  32 .\" All rights reserved.
  33 .\"
  34 .\" Redistribution and use in source and binary forms, with or without
  35 .\" modification, are permitted provided that the following conditions
  36 .\" are met:
  37 .\" 1. Redistributions of source code must retain the above copyright
  38 .\"    notice, this list of conditions and the following disclaimer.
  39 .\" 2. Redistributions in binary form must reproduce the above copyright
  40 .\"    notice, this list of conditions and the following disclaimer in the
  41 .\"    documentation and/or other materials provided with the distribution.
  42 .\" 3. Neither the name of the University nor the names of its contributors
  43 .\"    may be used to endorse or promote products derived from this software
  44 .\"    without specific prior written permission.
  45 .\"
  46 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  47 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  48 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  49 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  50 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  51 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  52 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  53 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  54 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  55 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  56 .\" SUCH DAMAGE.
  57 .\"
  58 .\"     from: @(#)setregid.2    6.4 (Berkeley) 3/10/91
  59 .\"
  60 .Dd January 5, 2001
  61 .Dt SETREGID 2
  62 .Os
  63 .Sh NAME
  64 .Nm setregid
  65 .Nd set real and effective group ID's
  66 .Sh LIBRARY
  67 .Lb libc
  68 .Sh SYNOPSIS
  69 .In unistd.h
  70 .Ft int
  71 .Fn setregid "gid_t rgid" "gid_t egid"
  72 .Sh DESCRIPTION
  73 .Bf -symbolic
  74 This interface is made obsolete by the saved ID functionality in
  75 .Xr setgid 2
  76 and
  77 .Xr setegid 2 .
  78 .Ef
  79 .Pp
  80 The real and effective group ID's of the
  81 current process are set according to the arguments.
  82 If the real group ID is changed, the saved group ID is changed to the
  83 new value of the effective group ID.
  84 .Pp
  85 If
  86 .Fa rgid
  87 or
  88 .Fa egid
  89 is \-1, the current gid is filled in by the system.
  90 Unprivileged users may change the real group
  91 ID to the effective group ID, and may change the effective group ID to the
  92 real group ID or the saved group ID; only the super-user may
  93 make other changes.
  94 .Pp
  95 The
  96 .Fn setregid
  97 function has been used to swap the real and effective group
  98 IDs in set-group-ID programs to temporarily relinquish the set-group-ID
  99 value.
 100 This purpose is now better served by the use of the
 101 .Fn setegid
 102 function (see
 103 .Xr setgid 2 ) .
 104 .Pp
 105 When setting the real and effective group IDs to the same value, this
 106 function is equivalent to the
 107 .Fn setgid
 108 function.
 109 When setting only the effective group ID, this function is equivalent to
 110 the
 111 .Fn setegid
 112 function.
 113 .Sh RETURN VALUES
 114 Upon successful completion, a value of 0 is returned.
 115 Otherwise, a value of \-1 is returned and
 116 .Va errno
 117 is set to indicate the error.
 118 .Sh ERRORS
 119 .Bl -tag -width Er
 120 .It Bq Er EPERM
 121 The current process is not the super-user and a change
 122 other than changing the effective group-id to the real group-id
 123 was specified.
 124 .El
 125 .Sh SEE ALSO
 126 .Xr getgid 2 ,
 127 .Xr setegid 2 ,
 128 .Xr setgid 2 ,
 129 .Xr setuid 2
 130 .Sh HISTORY
 131 The
 132 .Fn setregid
 133 function call appeared in
 134 .Bx 4.2 .
 135 An incompatible version was implemented in
 136 .Bx 4.4 .
 137 It was reimplemented in
 138 .Nx 1.2
 139 in a way compatible with
 140 .Bx 4.3 ,
 141 SunOS and Linux, but should not be used in new code.