From b0266169d4f5f1e4434a9304bf1c0bc6f29665ee Mon Sep 17 00:00:00 2001 From: Xin LI Date: Tue, 27 Dec 2011 10:34:00 +0000 Subject: [PATCH] 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 --- lib/libc/sys/Makefile.inc | 1 + lib/libc/sys/rtprio.2 | 98 ++++++++++++++++++++++++++++++++------- 2 files changed, 82 insertions(+), 17 deletions(-) diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index ea38b51b6319..073220e35fcc 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 afed81e2d98c..faad9417c55c 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 +.\" 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 .