unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



priocntl(2)							  priocntl(2)



NAME

  priocntl - manage scheduling properties of process

SYNOPSIS

  #include <&lt;sys/types.h>&gt;
  #include <&lt;sys/priocntl.h>&gt;
  #include <&lt;sys/rtpriocntl.h>&gt;
  #include <&lt;sys/tspriocntl.h>&gt;

  long priocntl(
	  idtype_t idtype,
	  id_t id,
	  int cmd,
	  void *arg );

PARAMETERS

  idtype
      Identifies the type of process to	be affected.  It is used with the id
      parameter	to specify the process or group	of processes that will
      change.

  id  Specifies	the process ID,	parent process ID, process group ID, session
      ID, class	ID, user ID, or	group ID of a process or group of processes.
      It is used with the idtype parameter.

  cmd Specifies	the how	the process or group of	processes are affected.

  arg Specifies	a pointer to a structure.

DESCRIPTION

  The priocntl function	is used	to change the class, priority, and other
  scheduling properties	of one or more active processes.  Processes are
  divided into four classes: real-time,	time-sharing, POSIX round robin, and
  the POSIX fifo class.	 Although the class and	attributes of a	process
  within a class can change, each class	has predefined scheduling properties
  that cannot change.

  To identify a	process	or set of processes that you want to change, you must
  specify the id and idtype parameters.	 The cmd parameter defines how the
  process or set of processes is to be affected. Depending on which cmd
  parameter you	select,	the data type and value	for the	arg parameter
  differs.

  This discussion of the priocntl function is divided into the following sec-
  tions:

    +  Process Selection

    +  Command Descriptions

    +  Command Arguments

    +  Scheduling and Priority Classes

    +  Include Files

  The RESTRICTIONS section additionally	describes instances in which a class
  or process may not change.

  Process Selection


  Using	the idtype and id parameters, you can specify a	group or group of
  processes that are to	be affected by the priocntl function.  The definition
  of the id parameter is determined by the value of the	idtype parameter as
  follows:

  ______________________________________________________
  idtype   id
  ______________________________________________________
  P_PID

	   Defines id as a process ID.	A single process
	   with	this process ID	is targeted.
  P_PPID

	   Defines id as a parent process ID.  All
	   processes with this specific	parent process
	   ID are targeted.
  P_PGID

	   Defines id as a process group ID.  All
	   processes with this specific	process	group ID
	   are targeted.
  P_SID

	   Defines id as a session ID.	All processes
	   within the specified	session	are targeted.
  P_CID

	   Defines id as a class ID.  All processes
	   within the specified	class are targeted.
  P_UID

	   Defines id as a user	ID.  All processes
	   within the effective	user ID	are targeted.
  P_GID

	   Defines id as a group ID.  All processes
	   within the effective	group ID are targeted.
  P_ALL

	   The value of	id is ignored.	All existing
	   processes are targeted for change.  See the
	   RESTRICTIONS	section	for exceptions.
  ______________________________________________________

  The id parameter can also specify the	value P_MYID which, when used with
  the idtype parameter,	specifies the calling process's	process	ID, parent
  process ID, process group ID,	session	ID, class ID, user ID, or group	ID.

  Command Descriptions


  The five commands currently supported	by the priocntl	function are as	fol-
  lows:

  PC_GETCID
      Retrieves	the class ID and class attributes for a	specific class given
      the class	name.  The idtype and id arguments are ignored.	If the value
      of the arg parameter is non-null,	the class ID and attribute data	are
      returned in a pcinfo_t structure that is discussed in the	next subsec-
      tion.  If	the value of the arg parameter is null,	attribute data is not
      returned,	but the	priocntl function does return the configured number
      of classes.

  PC_GETCLINFO
      Retrieves	the class name and class attributes for	a specific class
      given the	class ID.  The idtype and id arguments are ignored.  If	the
      value of the arg is non-null, the	class name and attribute data is
      returned in a pcinfo_t structure that is discussed in the	next
      subsection.  If the value	of the arg parameter is	null, attribute	data
      is not returned, but the priocntl	function returns the configured
      number of	classes	(including the sys class).

  PC_SETPARMS
      Sets the class and class-specific	scheduling parameters of the process
      or processes specified by	the id and idtype parameters. The arg parame-
      ter is a pointer to a pcparms_t structure	that is	discussed in the next
      subsection.

  PC_GETPARMS
      Retrieves	either the class or class-specific scheduling parameters of a
      process or both.	The process type is specified by the id	and idtype
      parameters.  The arg parameter points to a pcparms_t structure that is
      discussed	in the next subsection.

  PC_ADMIN
      Specified	for use	by a specific command and is not intended for general
      use by any other application.

  Command Arguments


  The data type	and value of the arg parameter is specific to the type of
  command specified by the cmd parameter.  This	section	highlights the value
  for the arg parameter	as it pertains to the commands.

  For both the PC_GETCID and PC_GETCLINFO commands, the	arg parameter if not
  null,	points to the following	structure:

       typedef struct {
	     id_t  pc_cid;
	     char  pc_clname[PC_CLNMSZ];
	     long  pc_clinfo[PC_CLINFOSZ];
       } pcinfo_t;

  For the PC_GETCID command, the pc_cid	field specifies	the class ID on
  return. The pc_clname	field specifies	the name of the	class whose attri-
  butes	you are	retrieving.  The pc_clinfo field specifies the class attri-
  butes	on return. The format of the attribute data that is returned is
  defined by the <&lt;sys/rtpriocntl.h>&gt; or the <&lt;sys/tspriocntl.h>&gt; header files.

  For the PC_GETCINFO command, the pc_cid field	specifies the class ID of the
  class	whose attributes you are retrieving.  The pc_clname field specifies
  the class name on return.  The pc_clinfo field specifies the class attri-
  butes	on return. The format of the attribute data that is returned is
  defined by the <&lt;sys/rtpriocntl.h>&gt; or the <&lt;sys/tspriocntl.h>&gt; header files.

  For both the PC_SETPARMS and PC_GETPARMS command, the	arg parameter points
  to the following structure:

       typedef struct {
	     id_t  pc_cid;
	     char  pc_clparms[PC_CLPARMSZ];
       } pcparms_t;

  For PC_SETPARMS, the pc_cid field specifies the class	ID that	you want to
  set. The pc_clparms field contains the class specific	parameters you are
  setting.  The	PC_CLPARMSZ argument specifies the length of pc_clparms	field
  and is defined in <&lt;sys/priocntl.h>&gt;.  The format of the class specific	data
  is defined by	the <&lt;sys/rtpriocntl.h>&gt; or <&lt;sys/tspriocntl.h>&gt; header file.
  These	formats	are discussed in more detail under the discussion of the
  available classes.

  For the PC_GETPARMS command, the pc_cid field	specifies the class ID.	 This
  is the class ID returned by the priocntl PC_GETCID request. The special
  class	ID PC_CLNULL may also be assigned to the pc_cid	parameter. The
  pc_pcparms field specifies the buffer	that contains the class-specific
  scheduling parameters.  The PC_CLPARMSZ argument specifies the length	of
  pc_clparms buffer and	is defined in <&lt;sys/priocntl.h>&gt;.	 The format of the
  class	specific data is defined by the	<&lt;sys/rtpriocntl.h>&gt; or
  <&lt;sys/tspriocntl.h>&gt; header file.  These formats are discussed in more detail
  under	the discussion of the available	classes.

  For the PC_GETPARMS command, the contents of the pc_clparms field is deter-
  mined	by the contents	of the pc_cid field as follows:

    +  If the pc_cid field specifies a configured class	and the	process	that
       belongs to that class was specified by the idtype and the id parame-
       ters or by the procset structure, the pc_clparms	field contains the
       scheduling parameters of	that process. If the process does not exist
       or the process does not belong to the specified class, the priocntl
       function	returns	the value -1 with errno	set to [ESRCH].

    +  If the pc_cid field specifies a configured class	and a set of
       processes is specified, only the	scheduling parameters of one process
       belonging to the	specified class	is returned in this field.  The
       priocntl	function returns the process ID	of the selected	process.  In
       this instance, selecting	a process to return is class-dependent.	 If
       the specified process does not exist, or	if none	of the processes
       belongs to the specified	class, the priocntl function returns the
       value -1	with errno set to [ESRCH].

    +  If the pc_cid field contains PC_CLNULL and a single process is speci-
       fied, the class of the specified	process	is returned in the pc_cid
       field and its scheduling	parameters are returned	in the pc_clparms
       field.

    +  If this special class ID	and a single process is	specified, the class
       of the specified	process	is returned in the pc_cid field	and the
       scheduling parameters are returned in the pc_clparms field.

  Scheduling and Priority Classes


  There	are four types of classifications that can be used when	managing the
  scheduling priorities	of a process or	set of processes. These	classes	are
  the real-time, time-sharing, POSIX round-robin, and the POSIX	fifo classes
  discussed in the next	sections.

  Real-time Class


  Processes that require quick response	and complete control of	its schedul-
  ing priorities through the user or application are placed in this class.
  The real-time	class provides a fixed scheduling policy that can only be
  changed by an	explicit request from either the user or application.  If
  this class is	configured on the system, any running real-time	process
  should obtain	the services of	the CPU	before a process that belongs to
  another class.

  To distinguish the priority of processes within the real-time	class, all
  processes are	assigned a priority value.  A priority value can range from
  zero (0) to x, where x is a configurable value that can be specified for a
  specific installation	using the PC_GETCID or PC_GETCLINFO commands. The
  higher the numerical priority	value of a process, the	higher its priority
  on the system.

  Each priority	value that is configured into the system has a separate
  scheduling queue that	the system's process scheduler manages.	Processes
  with the same	priority value share the same scheduling queue.	All processes
  within a queue are placed in First-In-First-Out (FIFO) order.

  The priocntl function	not only controls priority, it also controls the time
  quantum that is allotted to a	process	in the real-time class.	 The time
  quantum value	determines the maximum time that a running process which has
  not entered a	resource or event wait state (sleep) may run.  Note that
  regardless of	the time quantum specified, if another process at a higher
  priority makes a request to run, a running process may be preempted before
  receiving its	full time quantum.  A process that is preempted	by a higher
  priority process remains first its scheduling	queue with the remainder of
  its specified	time quantum still available.

  Note that after a fork system	call by	a real-time time process, the parent
  process continues to run while the child process inherits the	priority
  value	of the parent and is placed at the back	of the queue.

  The structures used by the real time class to	define the scheduling priori-
  ties and class attributes of a process are discussed in the section on
  Include Files.

  To change the	class of a process to real-time	(from any other	class) the
  process invoking the priocntl	function must have superuser privileges.  In
  order	to change the priority or time quantum setting of a real-time process
  the process invoking the priocntl function must have superuser privileges
  or must itself be a real-time	process	whose real or effective	user ID
  matches the real of effective	user ID	of the target process.

  The real-time	priority and time quantum are inherited

  Time-Sharing Class


  Processes that vary in CPU consumption, but which still require a reason-
  able response	time with some user or application control over	scheduling
  should be placed in this class.  To determine	the scheduling of processes
  within the time-sharing class, a user	priority value is assigned to a	pro-
  cess.	 This value may	range from -x to +x, where the value of	x is confi-
  gurable and may be determined	for a specific installation using the PC_CID
  or PC_GETCLINFO commands.

  Typically, a process with a higher user priority runs	before a process with
  a lower user priority	allowing some control over the scheduling of
  processes in this class.  However, other factors also	affect the priority
  of a process in this class such as the amount	of CPU usage already expended
  by a process.	 There is also a per process user priority limit that can be
  set for a given process.

  The structures used by the time sharing class	to define the scheduling
  priorities and class attributes of a process are discussed in	the section
  on Include Files.

  POSIX	Round Robin Class


  This class is	the same as the	real-time class	when a finite time quantum is
  specified.  The POSIX	round-robin class uses the same	structures as the
  real-time class to define the	scheduling priorities and attributes of	a
  process.

  To set or request the	scheduling parameters for a POSIX round	robin class,
  only one process can be selected.  If	more than one process is selected,
  all POSIX processes are ignored.  This is true even when all of the
  processes in the specified set belong	to the POSIX round-robin scheduling
  class.

  The priority value for a processes in	this class has the range -20 to	20.
  The time quantum must	be a valid time	quantum	value and not a	reserved
  value	as discussed in	the Include Files section.






  POSIX	Fifo Class


  This class is	the same as the	real-time class	when an	infinite time quantum
  is specified.	 The POSIX fifo	class uses the same structures as the real-
  time class to	define the scheduling priorities and attributes	of a process.

  To set or request the	scheduling parameters for a POSIX fifo class, only
  one process can be selected.	If more	than one process is selected, all
  POSIX	processes are ignored. This is true even when all of the processes in
  the specified	set belong to the POSIX	fifo scheduling	class.

  The priority value specified for processes has the range -20,	20. There are
  restrictions set on the usage	of the time quantum field as discussed in the
  Include Files	section.

  Include Files


  The real-time, POSIX round robin, and	POSIX fifo classes use structures
  defined in <&lt;sys/rtpriocntl.h>&gt;	to define the format and class specific
  priorities of	a process.  The	time sharing class uses	the structures
  defined in <&lt;sys/tspriocntl.h>&gt;	to define the format and class specific
  priorities of	a process.

  These	structures are defined in the next two sections.

  The rtpriocntl.h Header File


  The PC_GETCID	and PC_GETCLINFO commands return real time class attributes
  in the pc_clinfo buffer in using the following format:

       typedef struct {

       short rt_maxpri;	/* Maximum real-time priority */
       }   rtinfo_t;

  The rt_maxpri	field specifies	the configured maximum priority	value
  (rt_pri) for the real	time class.  For example, if rt_maxpri is x, the
  valid	real time priorities range from	zero (0) to x).

  If you use the PC_SETPARMS or	PC_GETPARMS commands and the pc_cid buffer
  specifies the	real-time class, the data in the pc_clparms buffer is in the
  following format:

       typedef struct {
	  short	rt_pri;	   /* Real-Time	priority */
	  ulong	rt_tqsecs; /* Seconds in time quantum */
	  long	rt_tqnsecs;/* Additional nanoseconds in
       quantum */
       } rtparms_t;

  rt_pri
      Used, depending on the command specified,	to either set the real time
      priority value or	to get the current real	time priority value.

      If the real time priority	value of a running or runnable process is
      set, this	causes the process to be placed	at the back of the scheduling
      queue for	the specified priority regardless of the previous priority
      value setting.  Note that	a running process can release the CPU and
      return to	the back of the	scheduling queue by resetting its priority
      value to its current real	time priority value.

      When getting the real time priority value, if the	pc_cid field
      specifies	the real time class and	more than one real time	process	is
      specified, the scheduling	parameters of the real time process with the
      highest priority value of	the set	is returned adn	the process ID of
      this process is returned by the priocntl function.  If more than one
      process shares the highest priority, the one returned is
      implementation-dependent

      Note that	you can	change the time	quantum	of a process without setting
      the priority or affecting	the process's position on the queue. In	this
      instance,	the rt_pri field should	be set to the reserved value
      RT_NOCHANGE defined below.  Specifying this value	RT_NOCHANGE when
      changing the class of a process to real-time from	some other class
      results in the real time priority	being set to zero.

  rt_tqsecs
      Used, depending on the command specified,	to set or get the time quan-
      tum associated with a process or group of	processes.

      The rt_tqsecs field specifies the	number of seconds in the time quan-
      tum.

  rt_tqnsecs
      Used, depending on the command specified,	to set or get the time quan-
      tum associated with a process or group of	processes.

      The rt_tqnsecs field specifies the number	of additional nanoseconds in
      the quantum. Specifying a	value that exceeds 999,999,999 in the
      rt_tqnsecs field results in an error.  For rt_tqnsecs, the specified
      time quantum length is rounded up	by the system to the next integral
      multiple of the system clock's resolution.

      The maximum time quantum that can	be specified is	implementation-
      specific and equal to LONG_MAX ticks which is defined in <&lt;sys/time>&gt;.
      Requesting a time	quantum	greater	than the maximum results in error.
      Requesting a time	quantum	of zero	by setting both	rt_tqsecs and
      rt_tqnsecs to zero results in an error.

      The rt_tqnsecs field can also be set to one of the following reserved
      values (defined in <&lt;sys/rtpriocntl.h>&gt;). If one of	these values is
      specified, rt_tqsecs is ignored. Note that these values may not be used
      if your process or process is in the POSIX round robin class:

      RT_TQINF
	  Sets an infinite time	quantum.  This must be used if you have
	  selected the POSIX fifo class	for your process or processes.

      RT_TQDEF
	  Sets the time	quantum	to the default for this	priority.

      RT_NOCHANGE
	  Does not set a time quantum. Specifying this value when changing
	  the class of a process to real time from some	other class is
	  equivalent to	specifying RT_TQDEF.








  Setup	of Structures in tspriocntl.h


  The PC_GETCID	and PC_GETCLINFO commands return time-sharing class attri-
  butes	in the pc_clinfo buffer	in the following format:

       typedef struct {
	 short ts_maxupri;  /* Limits of user priority range */
       } tsinfo_t;

  The ts_maxupri field specifies the configured	maximum	user priority value
  for the time-sharing class.  If the ts_maxupri field is 2x1, the valid
  range	for both user priorities and user priority limits is from -x to	+x.

  If you use the PC_SETPARMS or	PC_GETPARMS commands and the pc_cid buffer
  specifies the	time sharing class, the	data in	the pc_clparms buffer is in
  the following	format:

       typedef struct {
	 short ts_uprilim;  /* Time-Sharing user priority limit	*/
	 short ts_upri;	    /* Time-Sharing user priority */
       } tsparms_t;

  ts_uprilim
      Specifies	the maximum user priority limit	for a process or set of
      processes.

      All time sharing processes can lower its own ts_uprilim value (or	that
      of another process with the same user ID). Only a	time-sharing process
      with superuser privileges	can increase this value.

      If changing the class of a process to the	time sharing class from	some
      other class, superuser privileges	are required to	set the	initial
      ts_uprilim to a value greater than zero (0). Attempts by a
      nonprivileged process to increase	this value or to set an	initial	value
      greater than zero	(0) results in an error.

  ts_upri
      Specifies	the user priority limit	of a process or	set of processes.

      If used with the PC_GETPARMS command and the pc_cid field	specifies the
      time-sharing class and more than one time-sharing	process	is specified,
      the scheduling parameters	of the time-sharing process with the highest
      ts_upri value among the specified	processes is returned and the process
      ID of this process is returned by	the priocntl function.	If there is
      more than	one process sharing the	highest	user priority, the one
      returned is implementation-dependent.

      Any time sharing process can set its own ts_upri value (or that of
      another process with the same user ID) to	any value less than or equal
      to the process's ts_uprilim value.  Attempts to set the ts_upri above
      the ts_uprilim (and/or set the ts_uprilim	value below the	ts_upri)
      value results in the ts_upri value being set equal to the	ts_uprilim
      value.

  Note that a reserved value, TS_NOCHANGE defined in <&lt;sys/tspriocntl.h>&gt;) can
  be used to set either	the ts_uprilim or ts_upri value	without	affecting the
  other.  Specifying TS_NOCHANGE for the ts_upri value when the	ts_uprilim
  value	is set below the current ts_upri value causes the ts_upri value	to be
  set equal to the ts_uprilim value that is being set.

  Specifying TS_NOCHANGE for a parameter when changing the class of a process
  to time-sharing (from	some other class) causes the parameter to be set to a
  default value. The default value of the ts_uprilim is	zero (0) and the
  default for ts_upri is to set	it equal to the	ts_uprilim which is being
  set.

  The time-sharing user	priority and user priority limit are inherited across
  the fork and exec functions.



NOTES

  The following	notes also apply:

    +  If a process which is not running in a scheduling class recognized by
       priocntl	attempts to use	P_CID with P_MYID, a -1	will be	returned with
       errno set to [EINVAL].

    +  The priocntl function cannot be used in multithreaded applications.
       Attempts	to do so result	in failure.

RESTRICTIONS

  Some restrictions exist when changing	the class or priorities	of a process
  or group of processes	as follows:

    +  The sys scheduling class	is a special purpose category that is used
       solely to manage	the scheduling priorities of special system processes
       such as the swapper.  The class of a process that belongs to the	sys
       class cannot be changed (with the exception of the init process).
       Attempts	to change the class or priorities of a process in the sys
       class are ignored by the	priocntl function.

       The class or scheduling properties of the init process (Process ID 1)
       can be changed if it is the only	process	identified by the id and
       idtype arguments.  Although it can be placed in any class, it is	most
       suited in the time-sharing class.

    +  The default configuration enables an executable real-time process to
       run before other	processes.  Adverse system performance may occur if
       you are not careful when	specifying changes to real-time	processes.

RETURN VALUE

  Unless otherwise noted above,	the priocntl returns a value of	zero (0) on
  success.  Upon failure, the priocntl function	returns	-1 and sets errno to
  indicate the error.

ERRORS

  The priocntl function	fails under the	following conditions:

  [EPERM]
      The calling process does not have	the required permissions as explained
      above.

  [EINVAL]
      The argument cmd was invalid, an invalid or unconfigured class was
      specified, or one	of the parameters specified was	invalid.

  [ERANGE]
      The requested time quantum is out	of range.

  [ESRCH]
      None of the specified processes exist.

  [EFAULT]
      All or part of the area pointed to by one	of the data pointers is	out-
      side the process's address space.

  [ENOMEM]
      An attempt to change the class of	a process failed because of insuffi-
      cient memory.

  [EAGAIN]
      An attempt to change the class of	a process failed because of insuffi-
      cient resources other than memory	(for example, class-specific kernel
      data structures).

SEE ALSO

  Functions:  exec(2), fork(2),	getpriority(2),	priocntlset(2),	setprior-
  ity(2)

  Routines:  nice(3)