lib/libc/sys/sched_setparam.2

   1 .\" $FreeBSD: src/lib/libc/sys/sched_setparam.2,v 1.4.2.8 2001/12/14 18:34:01 ru Exp $
   2 .\" $DragonFly: src/lib/libc/sys/sched_setparam.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
   3 .\" Copyright (c) 1998 HD Associates, Inc.
   4 .\" 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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd March 12, 1998
  28 .Dt SCHED_SETPARAM 2
  29 .Os
  30 .Sh NAME
  31 .Nm sched_setparam ,
  32 .Nm sched_getparam
  33 .Nd set/get scheduling parameters
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sched.h
  38 .Ft int
  39 .Fn sched_setparam "pid_t pid" "const struct sched_param *param"
  40 .Ft int
  41 .Fn sched_getparam "pid_t pid" "struct sched_param *param"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn sched_setparam
  45 function sets the scheduling parameters of the process specified by
  46 .Fa pid
  47 to the values specified by the
  48 .Fa sched_param
  49 structure pointed to by
  50 .Fa param .
  51 The value of the
  52 .Fa sched_priority
  53 member in the
  54 .Fa param
  55 structure must be any integer within the inclusive priority range for
  56 the current scheduling policy of the process specified by
  57 .Fa pid .
  58 Higher numerical values for the priority represent higher priorities.
  59 .Pp
  60 In this implementation, if the value of
  61 .Fa pid
  62 is negative the function will fail.
  63 .Pp
  64 If a process specified by
  65 .Fa pid
  66 exists and if the calling process has permission, the scheduling
  67 parameters are set for the process whose process ID is equal to
  68 .Fa pid .
  69 .Pp
  70 If
  71 .Fa pid
  72 is zero, the scheduling parameters are set for the calling process.
  73 .Pp
  74 In this implementation, the policy of when a process can affect
  75 the scheduling parameters of another process is specified in
  76 .Xr p1003_1b
  77 as a write-style operation.
  78 .Pp
  79 The target process, whether it is running or not running, will resume
  80 execution after all other runnable processes of equal or greater
  81 priority have been scheduled to run.
  82 .Pp
  83 If the priority of the process specified by the
  84 .Fa pid
  85 argument is set higher than that of the lowest priority running process
  86 and if the specified process is ready to run, the process specified by
  87 the
  88 .Fa pid
  89 argument will preempt a lowest priority running process.  Similarly, if
  90 the process calling
  91 .Fn sched_setparam
  92 sets its own priority lower than that of one or more other nonempty
  93 process lists, then the process that is the head of the highest priority
  94 list will also preempt the calling process.  Thus, in either case, the
  95 originating process might not receive notification of the completion of
  96 the requested priority change until the higher priority process has
  97 executed.
  98 .Pp
  99 In this implementation, when the current scheduling policy for the
 100 process specified by
 101 .Fa pid
 102 is normal timesharing (SCHED_OTHER, aka SCHED_NORMAL when not POSIX-source)
 103 or the idle policy (SCHED_IDLE when not POSIX-source) then the behavior
 104 is as if the process had been running under SCHED_RR with a priority
 105 lower than any actual realtime priority.
 106 .Pp
 107 The
 108 .Fn sched_getparam
 109 function will return the scheduling parameters of a process specified
 110 by
 111 .Fa pid
 112 in the
 113 .Fa sched_param
 114 structure pointed to by
 115 .Fa param .
 116 .Pp
 117 If a process specified by
 118 .Fa pid
 119 exists and if the calling process has permission,
 120 the scheduling parameters for the process whose process ID is equal to
 121 .Fa pid
 122 are returned.
 123 .Pp
 124 In this implementation, the policy of when a process can obtain the
 125 scheduling parameters of another process are detailed in
 126 .Xr p1003_1b
 127 as a read-style operation.
 128 .Pp
 129 If
 130 .Fa pid
 131 is zero, the scheduling parameters for the calling process will be
 132 returned.  In this implementation, the
 133 .Fa sched_getparam
 134 function will fail if
 135 .Fa pid
 136 is negative.
 137 .Sh RETURN VALUES
 138 .Rv -std
 139 .Sh ERRORS
 140 On failure
 141 .Va errno
 142 will be set to the corresponding value:
 143 .Bl -tag -width Er
 144 .It Bq Er ENOSYS
 145 The system is not configured to support this functionality.
 146 .It Bq Er EPERM
 147 The requesting process doesn not have permission as detailed in
 148 .Xr p1003_1b .
 149 .It Bq Er ESRCH
 150 No process can be found corresponding to that specified by
 151 .Fa pid .
 152 .It Bq Er EINVAL
 153 For
 154 .Fn sched_setparam :
 155 one or more of the requested scheduling parameters
 156 is outside the range defined for the scheduling policy of the specified
 157 .Fa pid .
 158 .El
 159 .Sh SEE ALSO
 160 .Xr sched_getscheduler 2 ,
 161 .Xr sched_get_priority_max 2 ,
 162 .Xr sched_get_priority_min 2 ,
 163 .Xr sched_rr_get_interval 2 ,
 164 .Xr sched_setscheduler 2 ,
 165 .Xr sched_yield 2
 166 .Sh STANDARDS
 167 The
 168 .Fn sched_setparam
 169 and
 170 .Fn sched_getparam
 171 functions conform to
 172 .St -p1003.1b-93 .