NAME

       sched_setparam - set scheduling parameters (REALTIME)

SYNOPSIS

       #include <sched.h>

       int sched_setparam(pid_t pid, const struct sched_param *param);

DESCRIPTION

       The sched_setparam() function shall set the scheduling parameters of the process specified
       by pid to the values specified by the sched_param structure  pointed  to  by  param.   The
       value  of  the  sched_priority  member  in  the sched_param structure shall be any integer
       within the inclusive priority range for the  current  scheduling  policy  of  the  process
       specified by pid. Higher numerical values for the priority represent higher priorities. If
       the  value  of  pid  is  negative,  the  behavior  of  the  sched_setparam()  function  is
       unspecified.

       If  a  process  specified  by  pid  exists, and if the calling process has permission, the
       scheduling parameters shall be set for the process whose process ID is equal to pid.

       If pid is zero, the scheduling parameters shall be set for the calling process.

       The conditions under which one process has permission to change the scheduling  parameters
       of another process are implementation-defined.

       Implementations  may  require  the requesting process to have the appropriate privilege to
       set its own scheduling parameters or those of another process.

       The target process, whether it is running or not running, shall be moved to  the  tail  of
       the thread list for its priority.

       If  the  priority  of the process specified by the pid argument is set higher than that of
       the lowest priority running process and if the specified process  is  ready  to  run,  the
       process  specified  by  the  pid argument shall preempt a lowest priority running process.
       Similarly, if the process calling sched_setparam() sets its own priority lower  than  that
       of  one  or  more  other non-empty process lists, then the process that is the head of the
       highest priority list shall also preempt the calling process. Thus, in  either  case,  the
       originating  process  might  not  receive  notification of the completion of the requested
       priority change until the higher priority process has executed.

       If the scheduling policy of the target process is SCHED_SPORADIC, the value  specified  by
       the  sched_ss_low_priority  member  of  the param argument shall be any integer within the
       inclusive priority range for the sporadic  server  policy.  The  sched_ss_repl_period  and
       sched_ss_init_budget  members of the param argument shall represent the time parameters to
       be  used  by  the  sporadic  server  scheduling  policy  for  the  target   process.   The
       sched_ss_max_repl  member  of  the  param  argument  shall represent the maximum number of
       replenishments that are allowed to be pending simultaneously  for  the  process  scheduled
       under this scheduling policy.

       The  specified  sched_ss_repl_period  shall  be  greater  than  or  equal to the specified
       sched_ss_init_budget for the function to succeed; if it is not, then  the  function  shall
       fail.

       The  value of sched_ss_max_repl shall be within the inclusive range [1, {SS_REPL_MAX}] for
       the function to succeed; if not, the function shall fail.

       If the scheduling policy of the target process  is  either  SCHED_FIFO  or  SCHED_RR,  the
       sched_ss_low_priority, sched_ss_repl_period, and sched_ss_init_budget members of the param
       argument shall have no effect on the scheduling behavior. If the scheduling policy of this
       process  is  not SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC, the effects of these members are
       implementation-defined; this case includes the SCHED_OTHER policy.

       If the current scheduling policy for the process  specified  by  pid  is  not  SCHED_FIFO,
       SCHED_RR,    or SCHED_SPORADIC,   the result is implementation-defined; this case includes
       the SCHED_OTHER policy.

       The effect of  this  function  on  individual  threads  is  dependent  on  the  scheduling
       contention scope of the threads:

        * For  threads  with  system  scheduling  contention scope, these functions shall have no
          effect on their scheduling.

        * For  threads  with  process  scheduling  contention  scope,  the  threads'   scheduling
          parameters shall not be affected. However, the scheduling of these threads with respect
          to threads in other processes may be dependent on the scheduling  parameters  of  their
          process, which are governed using these functions.

       If  an  implementation  supports a two-level scheduling model in which library threads are
       multiplexed on top of several  kernel-scheduled  entities,  then  the  underlying  kernel-
       scheduled  entities for the system contention scope threads shall not be affected by these
       functions.

       The underlying kernel-scheduled entities for the process contention  scope  threads  shall
       have their scheduling parameters changed to the value specified in param. Kernel-scheduled
       entities for use by process contention scope threads that  are  created  after  this  call
       completes  shall inherit their scheduling policy and associated scheduling parameters from
       the process.

       This function is not atomic with respect to other threads in  the  process.   Threads  may
       continue  to execute while this function call is in the process of changing the scheduling
       policy for the underlying kernel-scheduled entities used by the process  contention  scope
       threads.

RETURN VALUE

       If successful, the sched_setparam() function shall return zero.

       If  the call to sched_setparam() is unsuccessful, the priority shall remain unchanged, and
       the function shall return a value of -1 and set errno to indicate the error.

ERRORS

       The sched_setparam() function shall fail if:

       EINVAL One or more of the requested scheduling parameters is outside the range defined for
              the scheduling policy of the specified pid.

       EPERM  The  requesting  process  does not have permission to set the scheduling parameters
              for the specified process, or does not have the  appropriate  privilege  to  invoke
              sched_setparam().

       ESRCH  No process can be found corresponding to that specified by pid.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       sched_getparam()  ,  sched_getscheduler()  ,  sched_setscheduler()  , the Base Definitions
       volume of IEEE Std 1003.1-2001, <sched.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .