setpriority() -- set nice value

SYNOPSIS

#include <sys/resource.h>

int setpriority(int which, id_t who, int value);

The setpriority() function sets the nice value of a process, all processes in a process group, or all processes for a specified user to the specified value. If the process is multi-threaded, the nice value affects all threads in the process. The default nice value is 0; lower nice values cause more favorable scheduling.

PARAMETERS

which: Specifies the type of target. Can be one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER.
who: Is the target of the setpriority() request; a process ID, process group ID, or user ID, respectively, depending on the value of which. A value of 0 indicates that the target is the current process, process group, or user.
value: Is the new nice value for the process. Values in the range [-NZERO,(NZERO-1)] are valid; values outside that range are silently clipped to this range.

RETURN VALUES

If successful, setpriority() returns 0. On failure, it returns -1 and sets errno to one of the following values:

EACCES: A request was made to change the nice value to a lower numeric value and the current process does not have appropriate privilege.
EINVAL: The value of the which parameter was not recognized, or the value of the who parameter is not a valid process ID, process group ID or user ID.
ENOTSUP: The value of the which or who parameter is not currently supported.
EPERM: A process was located, but neither the real nor effective user ID of the executing process match the effective user ID of the process whose nice value is to be changed.
ESRCH: No process could be locating using the which and who parameter values specified.

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

UNIX 98 documentation refers to NZERO as the default nice value, and then states that the value parameter is interpreted as (value + NZERO). This is confusing, and somewhat contradictory with standard UNIX behavior. The NuTCRACKER Platform implementation uses values of -NZERO to NZERO-1, which is the same thing. NZERO is defined as 20 in <limits.h>.

The PRIO_PGRP and PRIO_USER values for which are not currently supported; if either value is specified, setpriority() returns -1 with errno set to ENOTSUP.

When PRIO_PROCESS is specified for which, only 0 or the return value of getpid() may be specified for who. If any other value is specified, setpriority() returns -1 with errno set to ENOTSUP.

The NuTCRACKER Platform does not restrict a process from lowering its nice value (that is, raising its priority), as most UNIX platforms do. This is in keeping with the way the underlying Win32 APIs are implemented.

The following table shows the mapping between nice values and Win32 priorities. Refer to the Win32 documentation for SetThreadPriority() for more information on Win32 priority issues.

nice value	Win32 Priority
-20 to -16	`THREAD_PRIORITY_HIGHEST`
-15 to -6	`THREAD_PRIORITY_ABOVE_NORMAL`
-5 to +4	`THREAD_PRIORITY_NORMAL`
+5 to +14	`THREAD_PRIORITY_BELOW_NORMAL`
+15 to +19	`THREAD_PRIORITY_LOWEST`

This API results in a call to the Windows function SetThreadPriority() and does not adjust the Windows Priority Class. As a result, it is difficult to see that the priority has been changed with the MKS Toolkit ps utility or any other Windows utility (for example, the Windows Task Manager). The priority that has changed is referred to as the "dynamic thread priority" within a priority class and is only displayed by pview or similar utilities.

WARNING: Do not adjust the Windows Priority Class with the Windows SetPriorityClass() API. This can cause NuTCRACKER Platform core data structures to become corrupt and unusable or other undesirable results; all of which could result in the system hanging or worse.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

setpriority()
set nice value

Function