1 files changed, 45 insertions, 10 deletions
diff --git a/share/man/man9/suser.9 b/share/man/man9/suser.9
index 916ceec50233..39d5ed369157 100644
--- a/share/man/man9/suser.9
+++ b/share/man/man9/suser.9
@@ -31,7 +31,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$Id: suser.9,v 1.4 1997/03/07 02:53:37 jmg Exp $
+.\"	$Id: suser.9,v 1.5 1998/01/16 18:06:23 bde Exp $
 .\"
 .Dd Oct 15, 1996
 .Dt SUSER 9
@@ -43,25 +43,60 @@
 .Fd #include <sys/param.h>
 .Fd #include <sys/ucred.h>
 .Ft int
-.Fn suser "struct ucred *cred, u_short *acflag"
+.Fn suser "struct proc *proc"
+.Ft int
+.Fn suser_xxx "struct ucred *cred, struct proc *proc, int flags"
 .Sh DESCRIPTION
 The
 .Nm
-function checks if the credentials given include superuser powers.
+and
+.Nm suser_xxx
+functions checks if the credentials given include superuser powers.
+.Pp
+The
+.Nm
+function is the most common, and should be used unless special
+circumstances dictate otherwise.
+.Pp
+The
+.Nm suser_xxx
+function should be used when the credentials to be checked are
+not the process' own, when there is no process or when superuser
+powers should be extended to prisoned roots.
+.Pp
+By default a process does not command superuser powers if it has
+been imprisoned by the
+.Xr jail 2
+system call.  
+There are cases however where this is appropriate, and this can
+be done by setting the
+.Ql PRISON_ROOT
+bit in the flags argument to the
+.Nm suser_xxx 
+function.  It is important to review carefully in each case that
+this does not weaken the prison.  Generally only where the action
+is protected by the
+.Xr chroot 2
+implicit in
+.Xr jail 2
+call should such powers be granted.
 .Pp
 The
 .Nm
-routine notes the fact that superuser powers have been used in the 
-word pointed to by the second argument which should be a pointer to
-the p_acflags word of the proc structure. If the second argument is NULL
-then the usage is not noted.  Because part of it's function is to notice
+and
+.Nm suser_xxx
+functions notes the fact that superuser powers have been used in the
+process structure of the process specified. 
+Because part of its function is to notice
 whether super powers have been used, 
-.Nm 
-should be called after other permission possibilities have been exhausted.
+the functions should only be called after other permission 
+possibilities have been exhausted.
 .Sh RETURN VALUES
 The
 .Nm
-function returns 0 if the user has super powers and EPERM otherwise.
+and
+.Nm suser_xxx
+functions returns 0 if the user has super powers and EPERM otherwise.
 This is the
 .Em reverse logic
 of some other implementations of