dg_cpu_set_affinity(3T)        DG/UX R4.11MU05       dg_cpu_set_affinity(3T)


NAME
       dg_cpu_set_affinity, dg_cpu_get_affinity - change CPU affinity
       attributes of one or more LWP groups

SYNOPSIS
       #include <sys/dg_cpu.h>

       int dg_cpu_set_affinity(long version,
                               long selector,
                               long selector_value1,
                               long selector_value2,
                               dg_cpu_affinity_attr_t *attr_ptr);

       int dg_cpu_get_affinity(long version,
                               long selector,
                               long selector_value1,
                               long selector_value2,
                               dg_cpu_affinity_attr_t *attr_ptr);


   where:
       version         An integer version number, which should be set to
                       DG_CPU_AFFINITY_CURRENT_VERSION.
       selector        An integer indicating how to select the LWP groups
                       whose affinity attributes are being changed by a call
                       to dg_cpu_set_affinity(), or how to select the LWP
                       group whose affinity attributes are being retrieved
                       by a call to dg_cpu_get_affinity().
       selector_value1 An integer denoting the PID of the target process
                       containing the LWP groups whose affinity attributes
                       are being set or retrieved.
       selector_value2 An integer denoting the LWP group ID of the LWP group
                       whose affinity attributes are being set or retrieved;
                       this value is ignored when selector is other than
                       DG_CPU_AFFINITY_SELECT_PID_ONE_LWP_GROUP.
       attr_ptr        A pointer to a CPU affinity attributes object

DESCRIPTION
       The dg_cpu_set_affinity() function is used to change the CPU affinity
       attributes of one or more LWP groups in the target process to those
       stored in the affinity attributes object pointed to by attr_ptr.  The
       dg_cpu_get_affinity() function is used to retrieve the CPU affinity
       attributes of one LWP group in the target process; the attributes are
       stored into the affinity attributes object pointed to by attr_ptr.
       For a detailed discussion of CPU affinity and affinity attributes
       objects, refer to <sys/dg_cpu.h> and dg_cpu_affinity_attr_init(3T).

       Before calling dg_cpu_set_affinity() or dg_cpu_get_affinity(), the
       affinity attributes object pointed to by attr_ptr must be initialized
       by a call to dg_cpu_affinity_attr_init().  When the attributes object
       is no longer used, it should be destroyed by a call to
       dg_cpu_affinity_attr_destroy().

       The functions dg_cpu_set_affinity() and dg_cpu_get_affinity() can
       manipulate only one process at a time.  The PID of the target process
       is given by selector_value1.

       For dg_cpu_set_affinity(), the selector parameter determines which
       LWP groups are affected.  If selector is
       DG_CPU_AFFINITY_SELECT_PID_ALL_LWP_GROUPS, then the affinity
       attributes of all LWP groups in the target process are set to those
       contained in the attributes object pointed to by attr_ptr;  in this
       case, selector_value2 is ignored.  If selector is
       DG_CPU_AFFINITY_SELECT_PID_INIT_LWP_GROUP, then the affinity
       attributes of the initial LWP group in the target process are set to
       those contained in the attributes object pointed to by attr_ptr;  In
       this case, selector_value2 is also ignored.  If selector is
       DG_CPU_AFFINITY_SELECT_PID_ONE_LWP_GROUP, then the affinity
       attributes of the LWP group with LWP group ID given by
       selector_value2 in the target process are set to those contained in
       the attributes object pointed to by attr_ptr.

       For dg_cpu_get_affinity(), the selector parameter determines the LWP
       group whose affinity attributes are to be retrieved and then stored
       into the attributes object pointed to by attr_ptr.  If selector is
       DG_CPU_AFFINITY_SELECT_PID_ALL_LWP_GROUPS, then the affinity
       attributes for any LWP group in the target process are retrieved;  in
       this case, DG/UX currently retrieves the affinity attributes of the
       initial LWP group in the target process and selector_value2 is
       ignored.  If selector is DG_CPU_AFFINITY_SELECT_PID_INIT_LWP_GROUP,
       then the affinity attributes of the initial LWP group in the target
       process are retrieved; in this case, selector_value2 is also ignored.
       If selector is DG_CPU_AFFINITY_SELECT_PID_ONE_LWP_GROUP, then the
       affinity attributes of the LWP group with LWP group ID given by
       selector_value2 in the target process are retrieved.

       The value DG_CPU_INFO_CURRENT_VERSION should be passed as the version
       to both dg_cpu_set_affinity() and dg_cpu_get_affinity().

       If dg_cpu_get_affinity() fails, the contents of the attributes object
       pointed to by attr_ptr are undefined.

DIAGNOSTICS
   Return Value
       If successful, dg_cpu_set_affinity() and dg_cpu_get_affinity() return
       0.  Otherwise, they return -1 and set errno to indicate the error.

   Errors
       For each of the following conditions, dg_cpu_set_affinity() and
       dg_cpu_get_affinity() return -1 and set errno to the corresponding
       value:

       [EINVAL]  An invalid affinity attributes object has been specified.
                 This occurs when DG/UX has detected that the the affinity
                 attributes object pointed to by attr_ptr has not been
                 initialized by a previous call to
                 dg_cpu_affinity_attr_init() or has been corrupted.

       [EINVAL]  The value given by version does not refer to a supported
                 version number.

       [EINVAL]  The value given by selector is not
                 DG_CPU_AFFINITY_SELECT_PID_ALL_LWP_GROUPS,
                 DG_CPU_AFFINITY_SELECT_PID_INIT_LWP_GROUP, or
                 DG_CPU_AFFINITY_SELECT_PID_ONE_LWP_GROUP.

       [ESRCH]   The value given by selector_value1 does not denote the PID
                 of an active process.

       [ESRCH]   When selector is DG_CPU_AFFINITY_SELECT_PID_ONE_LWP_GROUP,
                 the value given by selector_value2 does not denote the LWP
                 group ID of an active LWP group in the target process

       For each of the following conditions, dg_cpu_set_affinity() returns
       -1 and sets errno to the corresponding value:

       [EINVAL]  The allowed CPU ID set contained in the affinity attributes
                 object pointed to by attr_ptr does not contain at least one
                 CPU that is currently online.

       [EPERM]   The caller does not have permission to change the affinity
                 attributes for the target process.

SEE ALSO
       dg_cpu_affinity_attr_init(3T), dg_cpu_affinity_attr_destroy(3T),
       dg_cpu_affinity_attr_set_cpu_id_set(3T),
       dg_cpu_affinity_attr_get_cpu_id_set(3T),
       dg_cpu_affinity_attr_set_minimum_level(3T),
       dg_cpu_affinity_attr_get_minimum_level(3T), dg_cpu_info(3T),
       dg_cpu_id_set_init(3T), dg_pthread_group_create(3T).
       dg_pthread_group_get_lwp_group_id(3T), dg_lwp_info(2), threads(5).

NOTE
       An application must link with -lthread in order to gain access to
       these functions.  However, the application need not use threads.

       In the current DG/UX implementation, a thread group is the user-level
       name for an LWP group.  Refer to dg_pthread_group_create(3T) for a
       discussion on creating thread groups.  Thread group IDs can be
       translated to LWP group IDs using
       dg_pthread_group_get_lwp_group_id(3T).  Refer to <sys/dg_cpu.h> for a
       discussion on the scheduling of LWP groups in the context of CPU
       affinity.


Licensed material--property of copyright holder(s)