xnu-2422.1.72.tar.gz

[apple/xnu.git] / bsd / man / man2 / getpriority.2

diff --git a/bsd/man/man2/getpriority.2 b/bsd/man/man2/getpriority.2
index 1c5713afd78e67368300530de634b2d99c883290..6e6d896356dbd3444754f61df1abdaf11d995ffb 100644 (file)
--- a/bsd/man/man2/getpriority.2
+++ b/bsd/man/man2/getpriority.2
@@ -41,15 +41,20 @@
 .Nm setpriority
 .Nd get/set program scheduling priority
 .Sh SYNOPSIS
 .Nm setpriority
 .Nd get/set program scheduling priority
 .Sh SYNOPSIS

-.Fd #include <sys/time.h>

 .Fd #include <sys/resource.h>
 .Ft int
 .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
 .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
 .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
 .Fa which
 and
 .Fa who


@@ -78,17 +83,39 @@ and a user ID for
 A zero value of
 .Fa who
 denotes the current process, process group, or user.
 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)
 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.
 .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
 .Sh RETURN VALUES
 Since
 .Fn getpriority


@@ -108,34 +135,82 @@ and
 .Fn setpriority
 will fail if:
 .Bl -tag -width Er
 .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
 .It Bq Er EINVAL
 .Fa Which

-was not one of
+is not one of

 .Dv PRIO_PROCESS ,
 .Dv PRIO_PGRP ,
 .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
 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:
 .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
 .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
 .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 ,
 .Sh SEE ALSO
 .Xr nice 1 ,
 .Xr fork 2 ,

+.Xr setiopolicy_np 3 ,
+.Xr compat 5 ,

 .Xr renice 8
 .Sh HISTORY
 The
 .Xr renice 8
 .Sh HISTORY
 The