bsd/man/man2/pthread_setugid_np.2

   1 .\"
   2 .\" Copyright (c) 2008 Apple Inc.  All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .Dd October 1, 2008
  24 .Dt PTHREAD_SETUGID_NP 2
  25 .Os
  26 .Sh NAME
  27 .Nm pthread_setugid_np
  28 .Nd Set the per-thread userid and single groupid.
  29 .Sh SYNOPSIS
  30 .Fd #include <sys/types.h>
  31 .Fd #include <sys/unistd.h>
  32 .Ft int
  33 .Fn pthread_setugid_np "uid_t uid, gid_t gid"
  34 .Sh DESCRIPTION
  35 .Fn pthread_setugid_np
  36 changes the current thread's effective, real, and saved userid and groupid to the requested
  37 userid and groupid (
  38 .Fa uid
  39 and
  40 .Fa gid
  41 , respectively) and clears all other groupids.
  42 .Pp
  43 .Fa uid
  44 can be the current real userid, KAUTH_UID_NONE, or, if the caller is privileged, any userid.
  45 .Fa gid
  46 can be the current real groupid or, if the caller is priviledged, any single groupid.
  47 .Pp
  48 Setting
  49 .Fa uid
  50 to KAUTH_UID_NONE means to "revert to the per process credential".
  51 .Sh CAVEATS
  52 Temporarily restoring root privileges for a non-privileged process is only possible on a per-process basis and not a per-thread basis.
  53 .Pp
  54 .Fn pthread_setugid_np
  55 is not intended as a privilege escalation mechanism.
  56 .Pp
  57 Do not use
  58 .Fn pthread_setugid_np.2
  59 in a security sensitive situation.
  60 .Sh RETURN VALUES
  61 Upon successful completion, a value of 0 is returned.
  62 Otherwise, -1 is returned and the global variable
  63 .Va errno
  64 is set to indicate the error.
  65 .Sh ERRORS
  66 .Fn pthread_setugid_np
  67 fails if one or more of the following are true:
  68 .\" ========
  69 .Bl -tag -width Er
  70 .It Bq EPERM
  71 The calling process does not have the correct credentials to set the override identity (i.e. The current credentials do not imply "super-user").
  72 .\" ========
  73 .It Bq EPERM
  74 If
  75 .Fa uid
  76 is set to KAUTH_UID_NONE,
  77 the current thread must already be assuming another identity in order to revert back.
  78 .\" ========
  79 .It Bq EPERM
  80 The current thread cannot already be assuming another identity.
  81 .El
  82 .Sh SEE ALSO
  83 .Xr setuid 2
  84 .Xr setgid 2
  85 .Xr seteuid 2
  86 .Xr setegid 2