Update rtprio(2) manual page to reflect the latest changes in -CURRENT as

well as provide documentation for rtprio_thread(2) system call.

MFC after:	1 month
X-MFC-after:	r228470

2 files changed, 82 insertions, 17 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index ea38b51..073220e 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -188,6 +188,7 @@ MLINKS+=read.2 pread.2 read.2 preadv.2 read.2 readv.2
 MLINKS+=readlink.2 readlinkat.2
 MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2
 MLINKS+=rename.2 renameat.2
+MLINKS+=rtprio.2 rtprio_thread.2
 .if !defined(NO_P1003_1B)
 MLINKS+=sched_get_priority_max.2 sched_get_priority_min.2 \
 	sched_get_priority_max.2 sched_rr_get_interval.2
diff --git a/lib/libc/sys/rtprio.2 b/lib/libc/sys/rtprio.2
index afed81e..faad941 100644
--- a/lib/libc/sys/rtprio.2
+++ b/lib/libc/sys/rtprio.2
@@ -1,3 +1,4 @@
+.\"-
 .\" Copyright (c) 1994, Henrik Vestergaard Draboel
 .\" All rights reserved.
 .\"
@@ -26,15 +27,40 @@
 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
+.\"-
+.\" Copyright (c) 2011 Xin LI <delphij@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 23, 1994
+.Dd December 27, 2011
 .Dt RTPRIO 2
 .Os
 .Sh NAME
-.Nm rtprio
-.Nd examine or modify a process realtime or idle priority
+.Nm rtprio ,
+.Nm rtprio_thread
+.Nd examine or modify realtime or idle priority
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -42,11 +68,18 @@
 .In sys/rtprio.h
 .Ft int
 .Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp"
+.Ft int
+.Fn rtprio_thread "int function" "lwpid_t lwpid" "struct rtprio *rtp"
 .Sh DESCRIPTION
 The
 .Fn rtprio
 system call
-is used to lookup or change the realtime or idle priority of a process.
+is used to lookup or change the realtime or idle priority of a process,
+or the calling thread.
+The
+.Fn rtprio_thread
+system call
+is used to lookup or change the realtime or idle priority of a thread.
 .Pp
 The
 .Fa function
@@ -54,10 +87,31 @@ argument
 specifies the operation to be performed.
 RTP_LOOKUP to lookup the current priority,
 and RTP_SET to set the priority.
-The
+.Pp
+For the
+.Fn rtprio
+system call,
+the
 .Fa pid
 argument
-specifies the process to be used, 0 for the current process.
+specifies the process to operate on,
+0 for the calling thread.
+When
+.Fa pid
+is non-zero,
+the system call reports the highest priority in the process,
+or sets all threads' priority in the process,
+depending on value of the
+.Fa function
+argument.
+.Pp
+For the
+.Fn rtprio_thread
+system call,
+the
+.Fa lwpid
+specifies the thread to operate on,
+0 for the calling thread.
 .Pp
 The
 .Fa *rtp
@@ -83,12 +137,12 @@ field ranges between 0 and
 .Pp
 Realtime and idle priority is inherited through fork() and exec().
 .Pp
-A realtime process can only be preempted by a process of equal or
-higher priority, or by an interrupt; idle priority processes will run only
-when no other real/normal priority process is runnable.
-Higher real/idle priority processes
-preempt lower real/idle priority processes.
-Processes of equal real/idle priority are run round-robin.
+A realtime thread can only be preempted by a thread of equal or
+higher priority, or by an interrupt; idle priority threads will run only
+when no other real/normal priority thread is runnable.
+Higher real/idle priority threads
+preempt lower real/idle priority threads.
+Threads of equal real/idle priority are run round-robin.
 .Sh RETURN VALUES
 .Rv -std rtprio
 .Sh ERRORS
@@ -102,12 +156,17 @@ The specified
 .Fa prio
 was out of range.
 .It Bq Er EPERM
-The calling process is not allowed to set the realtime priority.
+The calling thread is not allowed to set the realtime priority.
 Only
-root is allowed to change the realtime priority of any process, and non-root
-may only change the idle priority of the current process.
+root is allowed to change the realtime priority of any thread, and non-root
+may only change the idle priority of threads the user owns,
+when the
+.Xr sysctl 8
+variable
+.Va security.bsd.unprivileged_idprio
+is set to non-zero.
 .It Bq Er ESRCH
-The specified process was not found.
+The specified process or thread was not found or visible.
 .El
 .Sh SEE ALSO
 .Xr nice 1 ,
@@ -115,7 +174,8 @@ The specified process was not found.
 .Xr rtprio 1 ,
 .Xr setpriority 2 ,
 .Xr nice 3 ,
-.Xr renice 8
+.Xr renice 8 ,
+.Xr p_cansee 9 .
 .Sh AUTHORS
 .An -nosplit
 The original author was
@@ -124,3 +184,7 @@ This implementation in
 .Fx
 was substantially rewritten by
 .An David Greenman .
+The
+.Fn rtprio_thread
+system call was implemented by
+.An David Xu .