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