share/man/man9/suser.9

   1 .\"
   2 .\" Copyright (c) 1996 Julian R Elischer
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed by Kenneth Stailey.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. The name of the author may not be used to endorse or promote products
  16 .\"    derived from this software without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  23 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  24 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  25 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  26 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd August 30, 2007
  33 .Dt SUSER 9
  34 .Os
  35 .Sh NAME
  36 .Nm suser ,
  37 .Nm suser_cred
  38 .Nd check if credentials have superuser privileges
  39 .Sh SYNOPSIS
  40 .In sys/priv.h
  41 .Ft int
  42 .Fn suser "struct thread *td"
  43 .Ft int
  44 .Fn suser_cred "struct ucred *cred" "int flag"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn suser
  48 and
  49 .Fn suser_cred
  50 functions check if the credentials given include superuser powers.
  51 .Pp
  52 These interfaces have now been obsoleted by
  53 .Xr priv 9 ,
  54 and are provided only for compatibility with third party kernel modules that
  55 have not yet been updated to the new interface.
  56 They should not be used in any new kernel code.
  57 .Pp
  58 The
  59 .Fn suser
  60 function is the most common, and should be used unless special
  61 circumstances dictate otherwise.
  62 .Pp
  63 The
  64 .Fn suser_cred
  65 function should be used when the credentials to be checked are
  66 not the thread's own, when there is no thread, when superuser
  67 powers should be extended to imprisoned roots, or when the credential
  68 to be checked is the real user rather than the effective user.
  69 .Pp
  70 Whether or not a privilege is permitted in a
  71 .Xr jail 8
  72 depends on logic in
  73 .Fn prison_priv_check .
  74 .Pp
  75 In general, privileges are assigned based on the effective user ID; in some
  76 cases, the real user ID may be used.
  77 .Pp
  78 The
  79 .Fa flags
  80 field is currently unused.
  81 .Pp
  82 The
  83 .Fn suser
  84 and
  85 .Fn suser_cred
  86 functions note the fact that superuser powers have been used in the
  87 process structure of the process specified.
  88 Because part of their function is to notice
  89 whether superuser powers have been used,
  90 the functions should only be called after other permission
  91 possibilities have been exhausted.
  92 .Sh RETURN VALUES
  93 The
  94 .Fn suser
  95 and
  96 .Fn suser_cred
  97 functions return 0 if the user has superuser powers and
  98 .Er EPERM
  99 otherwise.
 100 This is the
 101 .Em reverse logic
 102 of some other implementations of
 103 .Fn suser
 104 in which a TRUE response indicates superuser powers.
 105 .Sh SEE ALSO
 106 .Xr chroot 2 ,
 107 .Xr jail 2 ,
 108 .Xr priv 9
 109 .Sh BUGS
 110 The
 111 .Fn suser
 112 and
 113 .Fn suser_cred
 114 functions do not, in fact, record that superuser privileges have been
 115 used, and have not done so since August 2000.