Manual Pages for UNIX Operating System command usage for man setpriority

Standard C Library Functions                      getpriority(3C)



NAME
     getpriority, setpriority - get and set the nice value

SYNOPSIS
     #include 

     int getpriority(int which, id_t who);


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


DESCRIPTION
     The getpriority() function obtains the nice value of a  pro-
     cess,  thread, or set of processes.  The setpriority() func-
     tion sets the nice value of a process,  thread,  or  set  of
     processes to value+NZERO, where NZERO is defined to be 20.


     Target entities are specified by the values of the which and
     who arguments.  The which argument can be one of the follow-
     ing values: PRIO_PROCESS, PRIO_PGRP, PRIO_USER,  PRIO_GROUP,
     PRIO_SESSION,  PRIO_LWP, PRIO_TASK, PRIO_PROJECT, PRIO_ZONE,
     or PRIO_CONTRACT, indicating that the who argument is to  be
     interpreted  as  a process ID, a process group ID, an effec-
     tive user ID, an effective group ID, a session ID, a  thread
     (lwp)  ID,  a task ID, a project ID, a zone ID, or a process
     contract ID, respectively.  A 0 value for the  who  argument
     specifies  the  current process, process group, or user. A 0
     value for the who argument is treated  as  valid  group  ID,
     session  ID,  thread (lwp) ID, task ID, project ID, zone ID,
     or process contract ID. A P_MYID value for the who  argument
     can  be  used to specify the current group, session, thread,
     task, project, zone, or process contract, respectively.


     If a specified process is multi-threaded, the nice value set
     with setpriority() affects all threads in the process.


     If more than one process is specified, getpriority() returns
     NZERO  less  than the lowest nice value pertaining to any of
     the specified entities,  and  setpriority()  sets  the  nice
     values of all of the specified processes to value+NZERO.


     The default nice value is NZERO.  Lower  nice  values  cause
     more favorable scheduling. The range of valid nice values is
     0 to NZERO*2-1. If value+NZERO is  less  than  the  system's
     lowest  supported  nice  value,  setpriority() sets the nice
     value to the  lowest  supported  value.  If  value+NZERO  is
     greater  than  the  system's  highest  supported nice value,



SunOS 5.11           Last change: 1 Apr 2008                    1






Standard C Library Functions                      getpriority(3C)



     setpriority() sets the nice value to the  highest  supported
     value.


     Only a process with appropriate  privileges  can  lower  the
     nice value.


     Any process or thread using SCHED_FIFO or SCHED_RR is  unaf-
     fected by a call to setpriority(). This is not considered an
     error. A process or  thread  that  subsequently  reverts  to
     SCHED_OTHER  will  not  have its priority affected by such a
     setpriority() call.


     The effect of changing the nice value  varies  depending  on
     the scheduling policy in effect.


     Since getpriority() can return the value  -1  on  successful
     completion,  it  is  necessary  to set errno to 0 prior to a
     call to getpriority(). If getpriority()  returns  the  value
     -1, then errno can be checked to see if an error occurred or
     if the value is a legitimate nice value.

RETURN VALUES
     Upon successful completion, getpriority() returns an integer
     in  the  range  from  -NZERO  to  NZERO-1.  Otherwise, -1 is
     returned and errno is set to indicate the error.


     Upon successful completion, setpriority() returns 0.  Other-
     wise, -1 is returned and errno is set to indicate the error.

ERRORS
     The getpriority() and setpriority() functions will fail if:

     ESRCH     No process or thread could be  located  using  the
               which and who argument values specified.


     EINVAL    The value of the which  argument  was  not  recog-
               nized,  or  the value of the who argument is not a
               valid process ID, process group ID, user ID, group
               ID,  session ID, thread (lwp) ID, task ID, project
               ID, or zone ID.



     In addition, setpriority() may fail if:





SunOS 5.11           Last change: 1 Apr 2008                    2






Standard C Library Functions                      getpriority(3C)



     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 being changed.


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


EXAMPLES
     Example 1 Example using getpriority()


     The following example returns the current scheduling  prior-
     ity for the process ID returned by the call to getpid(2).


       #include 
       ...
       int which = PRIO_PROCESS;
       id_t pid;
       int ret;

       pid = getpid();
       ret = getpriority(which, pid);


     Example 2 Example using setpriority()


     The following example sets the nice value  for  the  current
     process to 0.


       #include 
       ...
       int which = PRIO_PROCESS;
       id_t pid;
       int value = -20;
       int ret;

       pid = getpid();
       ret = setpriority(which, pid, value);


USAGE
     The getpriority() and setpriority() functions work  with  an
     offset  nice  value  (value-NZERO). The nice value is in the
     range 0 to 2*NZERO-1, while the return value  for  getprior-
     ity()  and  the third parameter for setpriority() are in the



SunOS 5.11           Last change: 1 Apr 2008                    3






Standard C Library Functions                      getpriority(3C)



     range -NZERO to NZERO-1.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


SEE ALSO
     nice(1),       renice(1),        sched_get_priority_max(3C),
     sched_setscheduler(3C), attributes(5), standards(5)



































SunOS 5.11           Last change: 1 Apr 2008                    4