nice() -- adjust process priority

SYNOPSIS

#include <unistd.h>

int nice(int incr);

The nice() function adds the specified increment to the current nice value for the process. Valid nice values are in the range -NZERO to NZERO-1; increments above or below those limits are silently modified to be in range.

Because nice() can return -1 on successful completion, it is necessary to set errno to EZERO before calling nice(). If nice() returns -1, errno can be checked to see if an error occurred or if the value is a legitimate nice value.

PARAMETERS

incr: Is the increment to apply to the current nice value.

RETURN VALUES

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

EPERM: A request was made to change the nice value to a lower numeric value and the current process does not have appropriate privilege.

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 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

nice()
adjust process priority

Function