Diff for /src/share/man/man9/suser.9 between versions 1.2 and 1.3

version 1.2, 2003/06/17 04:37:01 version 1.3, 2004/05/10 13:00:37
Line 1 Line 1
 .\"  .\"
   .\" Copyright (c) 2004 Hiten Pandya <hmp@dragonflybsd.org>
 .\" Copyright (c) 1996 Julian R Elischer  .\" Copyright (c) 1996 Julian R Elischer
 .\" All rights reserved.  .\" All rights reserved.
 .\"  .\"
Line 32 Line 33
 .\" SUCH DAMAGE.  .\" SUCH DAMAGE.
 .\"  .\"
 .\" $FreeBSD: src/share/man/man9/suser.9,v 1.9.2.5 2001/12/17 11:30:19 ru Exp $  .\" $FreeBSD: src/share/man/man9/suser.9,v 1.9.2.5 2001/12/17 11:30:19 ru Exp $
.\" $DragonFly: src/share/man/man9/suser.9,v 1.1 2003/06/16 05:38:36 dillon Exp $.\" $DragonFly$
 .\"  .\"
.Dd October 15, 1996.Dd May 10, 2004
 .Dt SUSER 9  .Dt SUSER 9
 .Os  .Os
 .Sh NAME  .Sh NAME
.Nm suser.Nm suser ,
.Nd check if we are superuser and note.Nm suser_cred ,
 .Nm suser_proc
 .Nd check for credentials for superuser privilege
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .In sys/param.h  .In sys/param.h
 .In sys/proc.h  .In sys/proc.h
 .In sys/ucred.h  .In sys/ucred.h
 .Ft int  .Ft int
.Fn suser "struct proc *proc".Fn suser "struct thread *td"
 .Ft int  .Ft int
.Fn suser_xxx "struct ucred *cred" "struct proc *proc" "int flags".Fn suser_cred "struct ucred *cred" "int flags"
 .Ft int
 .Fn suser_proc "struct proc *p"
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
andfamily of functions check if the credentials given include superuser privilege.
.Nm suser_xxx 
functions checks if the credentials given include superuser powers. 
 .Pp  .Pp
 The  The
.Nm.Fn suser
 function is the most common, and should be used unless special  function is the most common, and should be used unless special
 circumstances dictate otherwise.  circumstances dictate otherwise.
   The credential check is only necessary if the thread
   .Fa td
   is attached to a process.
 .Pp  .Pp
 The  The
.Nm suser_xxx.Nm suser_cred
 function should be used when the credentials to be checked are  function should be used when the credentials to be checked are
 not the process' own, when there is no process or when superuser  not the process' own, when there is no process or when superuser
powers should be extended to imprisoned roots.privilege should be extended to imprisoned roots.
 .Pp  .Pp
By default a process does not command superuser powers if it hasThe
 .Fn suser_proc
 function is used when the credentials to be checked are of a
 different process.
 .Pp
 By default a process does not command superuser privilege if it has
 been imprisoned by the  been imprisoned by the
 .Xr jail 2  .Xr jail 2
 system call.  system call.
There are cases however where this is appropriate, and this canThere are cases however where this is appropriate and can be done by
be done by setting thesetting the
 .Dv PRISON_ROOT  .Dv PRISON_ROOT
 bit in the flags argument to the  bit in the flags argument to the
.Nm suser_xxx.Nm suser_cred
function.  It is important to review carefully in each case thatfunction.
this does not weaken the prison.  Generally only where the actionIt is important to review carefully in each case that
is protected by thethis does not weaken the prison.
 Generally only where the action is protected by the
 .Xr chroot 2  .Xr chroot 2
 implicit in  implicit in
 .Xr jail 2  .Xr jail 2
call should such powers be granted.call should such privilege be granted.
 .Pp  .Pp
 The  The
.Nm.Fn suser ,
 .Fn suser_cred
 and  and
.Nm suser_xxx.Fn suser_proc
 functions note the fact that superuser powers have been used in the  functions note the fact that superuser powers have been used in the
 process structure of the process specified.  process structure of the process specified.
 Because part of their function is to notice  Because part of their function is to notice
whether superuser powers have been used,whether superuser privilege have been used,
 the functions should only be called after other permission  the functions should only be called after other permission
 possibilities have been exhausted.  possibilities have been exhausted.
 .Sh RETURN VALUES  .Sh RETURN VALUES
 The  The
.Nm.Fn suser ,
 .Fn suser_cred
 and  and
.Nm suser_xxx.Fn suser_proc
functions return 0 if the user has superuser powers andfunctions return
 .Li 0
 if the user has superuser privilege and
 .Er EPERM  .Er EPERM
 otherwise.  otherwise.
 This is the  This is the

Removed from v.1.2  
changed lines
  Added in v.1.3