.Nm setpriority
.Nd get/set program scheduling priority
.Sh SYNOPSIS
-.Fd #include <sys/time.h>
.Fd #include <sys/resource.h>
.Ft int
-.Fn getpriority "int which" "int who"
+.Fo getpriority
+.Fa "int which"
+.Fa "id_t who"
+.Fc
.Ft int
-.Fn setpriority "int which" "int who" "int prio"
+.Fo setpriority
+.Fa "int which"
+.Fa "id_t who"
+.Fa "int prio"
+.Fc
.Sh DESCRIPTION
-The scheduling
-priority of the process, process group, or user, as indicated by
+The scheduling priority of the process, process group, or user as indicated by
.Fa which
and
.Fa who
A zero value of
.Fa who
denotes the current process, process group, or user.
-.Fa Prio
+.Fa prio
is a value in the range -20 to 20. The default priority is 0;
lower priorities cause more favorable scheduling.
.Pp
The
.Fn getpriority
call returns the highest priority (lowest numerical value)
-enjoyed by any of the specified processes. The
+enjoyed by any of the specified processes.
+The
.Fn setpriority
call sets the priorities of all of the specified processes
to the specified value. Only the super-user may lower priorities.
+.Pp
+Additionally, the current thread or process can be placed in a background state
+by specifying PRIO_DARWIN_THREAD or PRIO_DARWIN_PROCESS for
+.Fa which .
+Only a value of zero (the current thread or process) is supported for
+.Fa who
+when setting or getting background state.
+.Fa prio
+is either 0 (to remove current thread from background status) or PRIO_DARWIN_BG
+(to set current thread into background state).
+When a thread or process is in a background state the scheduling priority is set
+to the lowest value, disk IO is throttled (with behavior similar to using
+.Xr setiopolicy_np 3
+to set a throttleable policy), and network IO is throttled for
+any sockets opened after going into background state. Any previously opened
+sockets are not affected.
+The
+.Fn getpriority
+call returns 0 when current thread or process is not in background state or 1
+when the current thread is in background state. Any thread or process can set
+itself into background state.
.Sh RETURN VALUES
Since
.Fn getpriority
call returns 0 if there is no error, or
-1 if there is.
.Sh ERRORS
-.Fn Getpriority
+.Fn getpriority
and
.Fn setpriority
will fail if:
.Bl -tag -width Er
-.It Bq Er ESRCH
-No process was located using the
-.Fa which
-and
-.Fa who
-values specified.
+.\" ==========
.It Bq Er EINVAL
.Fa Which
-was not one of
+is not one of
.Dv PRIO_PROCESS ,
.Dv PRIO_PGRP ,
+.Dv PRIO_USER ,
+.Dv PRIO_DARWIN_THREAD ,
+or
+.Dv PRIO_DARWIN_PROCESS .
+.\" ==========
+.It Bq Er EINVAL
+.Fa Who
+is not a valid process, process group, or user ID.
+.\" ==========
+.It Bq Er EINVAL
+.Fa Who
+is not 0 when
+.Fa which
+is
+.Dv PRIO_DARWIN_THREAD
or
-.Dv PRIO_USER .
+.Dv PRIO_DARWIN_PROCESS .
+.\" ==========
+.It Bq Er ESRCH
+No process can be located using the
+.Fa which
+and
+.Fa who
+values specified.
.El
.Pp
.Bl -tag -width Er
In addition to the errors indicated above,
.Fn setpriority
will fail if:
-.It Bq Er EPERM
-A process was located, but neither its effective nor real user
-ID matched the effective user ID of the caller.
+.\" ==========
.It Bq Er EACCES
-A non super-user attempted to lower a process priority.
+A non super-user attempts to lower a process priority.
+.\" ==========
+.It Bq Er EPERM
+A process is located,
+but neither its effective nor real user ID
+matches the effective user ID of the caller.
.El
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/resource.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.
+.Pp
+.Ft int
+.br
+.Fo getpriority
+.Fa "int which"
+.Fa "int who"
+.Fc ;
+.Pp
+.Ft int
+.br
+.Fo setpriority
+.Fa "int which"
+.Fa "int who"
+.Fa "int value"
+.Fc ;
+.Pp
+The type of
+.Fa who
+has changed.
.Sh SEE ALSO
.Xr nice 1 ,
.Xr fork 2 ,
+.Xr setiopolicy_np 3 ,
+.Xr compat 5 ,
.Xr renice 8
.Sh HISTORY
The
projects / apple / xnu.git / blobdiff