priocntl man page on Tru64

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
Tru64 logo
[printable version]

priocntl(2)							   priocntl(2)

NAME
       priocntl - manage scheduling properties of process

SYNOPSIS
       #include <sys/types.h> #include <sys/priocntl.h> #include <sys/rtprioc‐
       ntl.h> #include <sys/tspriocntl.h>

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

PARAMETERS
       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.	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.   Specifies  the  how
       the process or group of processes are affected.	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
       sections: 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 defi‐
       nition 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	 pro‐
		cesses	with  this specific parent process ID
		are targeted.
       P_PGID	Defines id as a process group ID.   All	 pro‐
		cesses	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
       follows: 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 subsection.	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.  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).   Sets  the
       class  and  class-specific scheduling parameters of the process or pro‐
       cesses specified by the id and idtype parameters. The arg parameter  is
       a  pointer  to a pcparms_t structure that is discussed in the next sub‐
       section.	 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.  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
       attributes you are retrieving.  The pc_clinfo field specifies the class
       attributes on return. The format of the attribute data that is returned
       is defined by the <sys/rtpriocntl.h> or the  <sys/tspriocntl.h>	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 attributes on return. The format of the attribute	data  that  is
       returned is defined by the <sys/rtpriocntl.h> or the <sys/tspriocntl.h>
       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 <sys/priocntl.h>.  The format of the
       class specific data is defined by the <sys/rtpriocntl.h> or <sys/tspri‐
       ocntl.h> 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 parame‐
       ter. 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  <sys/priocntl.h>.   The
       format  of the class specific data is defined by the <sys/rtpriocntl.h>
       or <sys/tspriocntl.h> 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
       determined 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 parameters	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
       scheduling  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_GET‐
       CLINFO 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 pro‐
       cesses 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
       priorities  and class attributes of a process are discussed in the sec‐
       tion 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 privi‐
       leges.  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 tar‐
       get process.

       The real-time priority and time quantum are inherited

   Time-Sharing Class
       Processes that vary in CPU consumption, but which still require a  rea‐
       sonable response time with some user or application control over sched‐
       uling 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 process.  This value may range from -x to +x,  where  the
       value of x is configurable and may be determined for a specific instal‐
       lation 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 prior‐
       ity  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  sec‐
       tion on Include Files.

   POSIX Round Robin Class
       This  class is the same as the real-time class when a finite time quan‐
       tum 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 schedul‐
       ing 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  dis‐
       cussed in the Include Files section.

   Include Files
       The real-time, POSIX round robin, and POSIX fifo classes use structures
       defined in <sys/rtpriocntl.h> to define the format and  class  specific
       priorities  of  a  process.  The time sharing class uses the structures
       defined in <sys/tspriocntl.h> 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  buf‐
       fer 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;

       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.  Used, depending on the command specified,  to  set
	      or  get  the  time quantum associated with a process or group of
	      processes.

	      The rt_tqsecs field specifies the number of seconds in the  time
	      quantum.	 Used,	depending  on the command specified, to set or
	      get the time quantum associated with a process or group of  pro‐
	      cesses.

	      The rt_tqnsecs field specifies the number of additional nanosec‐
	      onds 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 implementa‐
	      tion-specific and equal to LONG_MAX ticks which  is  defined  in
	      <sys/time>.   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 <sys/rtpriocntl.h>). If one of these
	      values  is specified, rt_tqsecs is ignored. Note that these val‐
	      ues may not be used if your process or process is in  the	 POSIX
	      round  robin class: Sets an infinite time quantum.  This must be
	      used if you have selected the POSIX fifo class for your  process
	      or  processes.   Sets  the  time quantum to the default for this
	      priority.	 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
       attributes 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  buf‐
       fer 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;

       Specifies the maximum user priority limit for a process or set of  pro‐
       cesses.

	      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.
	      Specifies	 the  user  priority limit of a process or set of pro‐
	      cesses.

	      If used with the PC_GETPARMS command and the pc_cid field speci‐
	      fies  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 speci‐
	      fied 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  <sys/tspriocntl.h>)
       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 prior‐
       ities of a process in the sys class are ignored by the  priocntl	 func‐
       tion.

	      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 pro‐
	      cesses.

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: The calling
       process does not have the required permissions as explained above.  The
       argument cmd was invalid, an invalid or unconfigured class  was	speci‐
       fied,  or  one  of the parameters specified was invalid.	 The requested
       time quantum is out of range.  None of the specified  processes	exist.
       All  or part of the area pointed to by one of the data pointers is out‐
       side the process's address space.  An attempt to change the class of  a
       process	failed	because	 of insufficient memory.  An attempt to change
       the class of a process failed because of insufficient  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)

								   priocntl(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net