rtprio_thread (2)

Leading comments

-
 Copyright (c) 1994, Henrik Vestergaard Draboel
 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
   ...

(The comments found at the beginning of the groff file "man2/rtprio_thread.2freebsd".)

NAME

rtprio rtprio_thread - examine or modify realtime or idle priority

LIBRARY

Lb libc

SYNOPSIS

In sys/types.h 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

DESCRIPTION

The Fn rtprio system call 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.

The Fa function argument specifies the operation to be performed. RTP_LOOKUP to lookup the current priority, and RTP_SET to set the priority.

For the Fn rtprio system call, the Fa pid argument 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.

For the Fn rtprio_thread system call, the Fa lwpid specifies the thread to operate on, 0 for the calling thread.

The Fa *rtp argument is a pointer to a struct rtprio which is used to specify the priority and priority type. This structure has the following form:

struct rtprio {
        u_short type;
        u_short prio;
};

The value of the type field may be RTP_PRIO_REALTIME for realtime priorities, RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. The priority specified by the prio field ranges between 0 and RTP_PRIO_MAX (usually 31) 0 is the highest possible priority.

Realtime and idle priority is inherited through fork() and exec().

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.

RETURN VALUES

Rv -std rtprio rtprio_thread

ERRORS

The Fn rtprio and Fn rtprio_thread system calls will fail if:

Bq Er EFAULT

The rtp pointer passed to Fn rtprio or Fn rtprio_thread was invalid.

Bq Er EINVAL

The specified Fa prio was out of range.

Bq Er EPERM

The calling thread is not allowed to set the realtime priority. Only 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 sysctl(8) variable security.bsd.unprivileged_idprio is set to non-zero.

Bq Er ESRCH

The specified process or thread was not found or visible.

SEE ALSO

nice(1), ps(1), rtprio(1), setpriority(2), nice(3), renice(8), p_cansee9

AUTHORS

An -nosplit The original author was An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk . This implementation in Fx was substantially rewritten by An David Greenman . The Fn rtprio_thread system call was implemented by An David Xu .