]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man2/getpriority.2
xnu-3248.20.55.tar.gz
[apple/xnu.git] / bsd / man / man2 / getpriority.2
... / ...
CommitLineData
1.\" $NetBSD: getpriority.2,v 1.4 1995/02/27 12:33:15 cgd Exp $
2.\"
3.\" Copyright (c) 1980, 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)getpriority.2 8.1 (Berkeley) 6/4/93
35.\"
36.Dd June 4, 1993
37.Dt GETPRIORITY 2
38.Os BSD 4
39.Sh NAME
40.Nm getpriority ,
41.Nm setpriority
42.Nd get/set program scheduling priority
43.Sh SYNOPSIS
44.Fd #include <sys/resource.h>
45.Ft int
46.Fo getpriority
47.Fa "int which"
48.Fa "id_t who"
49.Fc
50.Ft int
51.Fo setpriority
52.Fa "int which"
53.Fa "id_t who"
54.Fa "int prio"
55.Fc
56.Sh DESCRIPTION
57The scheduling priority of the process, process group, or user as indicated by
58.Fa which
59and
60.Fa who
61is obtained with the
62.Fn getpriority
63call and set with the
64.Fn setpriority
65call.
66.Fa Which
67is one of
68.Dv PRIO_PROCESS ,
69.Dv PRIO_PGRP ,
70or
71.Dv PRIO_USER ,
72and
73.Fa who
74is interpreted relative to
75.Fa which
76(a process identifier for
77.Dv PRIO_PROCESS ,
78process group
79identifier for
80.Dv PRIO_PGRP ,
81and a user ID for
82.Dv PRIO_USER ) .
83A zero value of
84.Fa who
85denotes the current process, process group, or user.
86.Fa prio
87is a value in the range -20 to 20. The default priority is 0;
88lower priorities cause more favorable scheduling.
89.Pp
90The
91.Fn getpriority
92call returns the highest priority (lowest numerical value)
93enjoyed by any of the specified processes.
94The
95.Fn setpriority
96call sets the priorities of all of the specified processes
97to the specified value. Only the super-user may lower priorities.
98.Pp
99Additionally, the current thread or process can be placed in a background state
100by specifying PRIO_DARWIN_THREAD or PRIO_DARWIN_PROCESS for
101.Fa which .
102Only a value of zero (the current thread or process) is supported for
103.Fa who
104when setting or getting background state.
105.Fa prio
106is either 0 (to remove current thread from background status) or PRIO_DARWIN_BG
107(to set current thread into background state).
108When a thread or process is in a background state the scheduling priority is set
109to the lowest value, disk IO is throttled (with behavior similar to using
110.Xr setiopolicy_np 3
111to set a throttleable policy), and network IO is throttled for
112any sockets opened after going into background state. Any previously opened
113sockets are not affected.
114The
115.Fn getpriority
116call returns 0 when current thread or process is not in background state or 1
117when the current thread is in background state. Any thread or process can set
118itself into background state.
119.Sh RETURN VALUES
120Since
121.Fn getpriority
122can legitimately return the value -1, it is necessary
123to clear the external variable
124.Va errno
125prior to the
126call, then check it afterward to determine
127if a -1 is an error or a legitimate value.
128The
129.Fn setpriority
130call returns 0 if there is no error, or
131-1 if there is.
132.Sh ERRORS
133.Fn Getpriority
134and
135.Fn setpriority
136will fail if:
137.Bl -tag -width Er
138.\" ==========
139.It Bq Er EINVAL
140.Fa Which
141is not one of
142.Dv PRIO_PROCESS ,
143.Dv PRIO_PGRP ,
144.Dv PRIO_USER ,
145.Dv PRIO_DARWIN_THREAD ,
146or
147.Dv PRIO_DARWIN_PROCESS .
148.\" ==========
149.It Bq Er EINVAL
150.Fa Who
151is not a valid process, process group, or user ID.
152.\" ==========
153.It Bq Er EINVAL
154.Fa Who
155is not 0 when
156.Fa which
157is
158.Dv PRIO_DARWIN_THREAD
159or
160.Dv PRIO_DARWIN_PROCESS .
161.\" ==========
162.It Bq Er ESRCH
163No process can be located using the
164.Fa which
165and
166.Fa who
167values specified.
168.El
169.Pp
170.Bl -tag -width Er
171In addition to the errors indicated above,
172.Fn setpriority
173will fail if:
174.\" ==========
175.It Bq Er EACCES
176A non super-user attempts to lower a process priority.
177.\" ==========
178.It Bq Er EPERM
179A process is located,
180but neither its effective nor real user ID
181matches the effective user ID of the caller.
182.El
183.Sh LEGACY SYNOPSIS
184.Fd #include <sys/types.h>
185.Fd #include <sys/resource.h>
186.Pp
187The include file
188.In sys/types.h
189is necessary.
190.Pp
191.Ft int
192.br
193.Fo getpriority
194.Fa "int which"
195.Fa "int who"
196.Fc ;
197.Pp
198.Ft int
199.br
200.Fo setpriority
201.Fa "int which"
202.Fa "int who"
203.Fa "int value"
204.Fc ;
205.Pp
206The type of
207.Fa who
208has changed.
209.Sh SEE ALSO
210.Xr nice 1 ,
211.Xr fork 2 ,
212.Xr setiopolicy_np 3 ,
213.Xr compat 5 ,
214.Xr renice 8
215.Sh HISTORY
216The
217.Fn getpriority
218function call appeared in
219.Bx 4.2 .