pset_create(2)							System Calls Manual						    pset_create(2)

NAME

       pset_create() - create a processor set

SYNOPSIS

DESCRIPTION

       The  function  creates an empty processor set with no processors.  Processor sets allow a subset of processors in the system to be isolated
       for exclusive use by specified threads and processes.  Only the threads bound to a processor set can execute on processors in that  proces-
       sor set.  The binding of threads and processes to processor sets is controlled by the function (see pset_bind(2)).

       A  unique  identifier  is  assigned  to the new processor set created by the function, and is returned to the caller in the memory location
       pointed to by newpset.  This value is valid only if the function return value is zero.

       A processor can be assigned to a processor set by the function.	A processor may not belong to more than  one  processor  set  at  a  time.
       There  may  be  an implementation dependent limit on the maximum number of processor sets that may exist (created and not destroyed) at any
       given time.

       Any user may create a new processor set with the function.  However, special permissions are needed to populate a processor set	with  pro-
       cessors	(see  pset_assign(2)),	to  execute  applications  in  a  processor  set  (see	pset_bind(2)),	or to destroy a processor set (see
       pset_destroy(2)).  There may be a per user limit on how many processor sets that users without the privilege may own.

       Every processor set is assigned ownership and access permission attributes.  The creator of a processor set becomes the	default  owner	of
       the processor set.

       The  READ, WRITE, and EXEC access permissions are defined for processor sets for three access modes --  Owner, Group, and Others -- similar
       to the UNIX file system access permissions.  The READ permission allows the caller to query about processor set	configuration,	the  WRITE
       permission  allows the caller to change processor set configuration and attributes, and the EXEC permission allows the caller to execute on
       processors in the processor set.  The function may be used to change the ownership and access permissions, whereas the function may be used
       to query the current ownership and access permissions.

       A system default processor set is created at system initialization time and cannot be destroyed.  The default processor set is always owned
       by the user with UID 0 and has the processor set ID of Processor 0 is always assigned to the default processor set and cannot be reassigned
       to another processor set.

   Note on Hyper-Threading
       On  systems  with  the  hyper-threading	capability enabled at the firmware level, each hyper-thread represents a logical processor (LCPU).
       Since the logical processors in the same physical processor core share common resources, interfaces dealing with workload migration or pro-
       cessor migration must operate at the physical processor core granularity.

       The following is a list of processor set attributes and their default values at processor set creation time (see pset_getattr(2)):

       Indicates the behavior on a request to bind a process
		 or a thread to a processor set that does not contain any processors.  By default, such a request will be rejected.

       GID of processor set's owner group.
		 The creator's gid is assigned by default.

       A flag to indicate if processors in the set are
		 configured to receive external I/O interrupts or not.	All processors by default are made available to receive interrupts.

       Indicates the behavior on a request to remove the last
		 processor  from  a  processor set.  By default, all processes/threads assigned to the processor set are reassigned to the default
		 processor set and the processor is reassigned as requested.

       On a system with the hyper-threading feature enabled, the LCPU attribute
		 indicates whether or not the processor cores in a processor set are enabled with logical  processors  (LCPU).	 By  default,  the
		 default processor set's attribute value is inherited at the time of creation.	The non-default processor set's can be modified by
		 but the default processor set's can only be modified by the dynamic kernel tunable command,

       Indicates the behavior on a request to destroy a
		 non-empty processor set.  The non-empty processor set refers to one that has at least one processor assigned to it.  By  default,
		 all  processors  and  processes/threads assigned to the processor set are reassigned to the system default processor set, and the
		 processor set is destroyed.

       UID of the processor set owner.
		 The processor set creator is the default owner.

       Access permissions for the processor set.
		 By default, the processor set owner has all permissions, whereas group and others have only READ and EXEC permissions.

       Processor sets define a scheduling allocation domain for threads and processes.	All threads may execute  only  on  processors  within  the
       assigned processor set.	The kernel load balancers work within the processor set boundary.  There is no load balancing across the processor
       set boundary although users can explicitly migrate threads and processes from one processor set to another  by  using  the  function.   The
       POSIX  RTSCHED  scheduler  (see	rtsched(2))  no longer works at the system level; its scheduling domain is restricted to the processor set
       boundary.

       System daemon threads created in the kernel are not restricted to a user defined processor set configuration.  They may run on any  proces-
       sor in the system as necessary.

       Use with to see if the processor set functionality is supported by the underlying HP-UX operating system version.

   Security Restrictions
       Some  or  all of the actions associated with this system call require the privilege.  Processes owned by the superuser have this privilege.
       Processes owned by other users may have this privilege, depending on system configuration.  See privileges(5) for  more	information  about
       privileged access on systems that support fine-grained privileges.

EXAMPLES

       Create a new processor set:

RETURN VALUE

       returns zero on successful completion.  Otherwise, -1 is returned and is set to indicate the error.

ERRORS

       fails if one or more of the following is true:

       The user has reached the per user limit on how many processor sets a
		    user without the privilege may own.

       The memory location pointed to by
		    newpset is not writable by the user.

       The memory location pointed to by
		    newpset is

       Processor sets cannot be created on a uniprocessor system.

       The user does not have necessary permissions to create a new processor set.

       A new processor set cannot be created at this time
		    due to lack of necessary system resources.

       The processor set functionality is not supported by the
		    underlying HP-UX version.

SEE ALSO

       kctune(1M),   psrset(1M),   pset_assign(2),  pset_bind(2),  pset_ctl(2),  pset_destroy(2),  pset_getattr(2),  pset_setattr(2),  rtsched(2),
       sysconf(2), privgrp(4), privileges(5).

																    pset_create(2)