'\" te .\" Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved. .TH processor_affinity 2 "23 Sep 2015" "SunOS 5.11" "System Calls" .SH NAME processor_affinity \- control a LWP's affinity for CPUs .SH SYNOPSIS .LP .nf #include #include \fBint\fR \fBprocessor_affinity\fR(\fBprocset_t\fR \fI*ps\fR, \fBuint_t\fR \fI*nids\fR, \fBid_t\fR \fI*ids\fR, \fBuint32_t\fR \fI*flags\fR); .fi .SH DESCRIPTION .sp .LP The \fBprocessor_affinity\fR system call determines a LWP (lightweight process) affinity for a set of CPUs and how strictly such affinity should be enforced. Similar to processor bindings, affinities determine on which processor(s) a LWP will be scheduled to execute on, with the advantage of allowing such behavior to be strong or weakly enforced, and with more flexibility when specifying the target processors. .sp .LP With strong affinity the target LWPs will only run on the specified processors, while weak affinity results in a best effort attempt at executing the LWPs on such CPUs. \fBprocessor_affinity\fR also provides more flexibility by allowing users to specify processors in terms of CPUs contained in a Processor Group or Leaf Locality Group, and also in terms of the processors where LWPs should not be scheduled on. .sp .LP The \fBps\fR argument identifies for which LWPs the call will be applied to through a \fBprocset\fR structure. For details, see \fBprocset.h\fR(3HEAD). The flags argument must contain valid combinations of the following options: .sp .ne 2 .mk .na \fB\fBPA_QUERY\fR\fR .ad .RS 18n .rt Query flags and affinities. .RE .sp .ne 2 .mk .na \fB\fBPA_CLEAR\fR\fR .ad .RS 18n .rt Clears any existing affinity. .RE .sp .ne 2 .mk .na \fB\fBPA_TYPE_CPU\fR\fR .ad .RS 18n .rt Indicates that the given IDs are processor IDs, when setting, and that the results of a query should return processor IDs. .RE .sp .ne 2 .mk .na \fB\fBPA_TYPE_PG\fR\fR .ad .RS 18n .rt Indicates that the given IDs are Processor Group IDs, when setting, and that the results of a query should return processor group IDs. Processor group \fB0\fR cannot be used. .RE .sp .ne 2 .mk .na \fB\fBPA_TYPE_LGRP\fR\fR .ad .RS 18n .rt Indicates that the given IDs are Locality Group IDs, when setting, and that the results of a query should return locality group IDs. Only the root or leaf \fBlgroups\fR are accepted. .RE .sp .ne 2 .mk .na \fB\fBPA_AFF_WEAK\fR\fR .ad .RS 18n .rt Prefer to run on specified CPUs. .RE .sp .ne 2 .mk .na \fB\fBPA_AFF_STRONG\fR\fR .ad .RS 18n .rt Only run on specified CPUs. .RE .sp .ne 2 .mk .na \fB\fBPA_NEGATIVE\fR\fR .ad .RS 18n .rt Avoid running on specified CPUs, used in conjunction with the affinity strength. .RE .sp .ne 2 .mk .na \fB\fBPA_NO_INH_EXEC\fR\fR .ad .RS 18n .rt Do not inherit affinities across \fBexec\fR(2). .RE .sp .ne 2 .mk .na \fB\fBPA_NO_INH_FORK\fR\fR .ad .RS 18n .rt Do not inherit affinities across \fBfork\fR(2). .RE .sp .ne 2 .mk .na \fB\fBPA_NO_INH_THR\fR\fR .ad .RS 18n .rt Do not inherit affinities across \fBthr_create\fR(3C). .RE .sp .LP When setting affinities, the \fBnids\fR argument points to a memory position holding the number of CPU, PG or LGRP identifiers to which affinity is being set, and \fBids\fR points to an array with the identifiers. Only one type of affinity must be specified, along with one affinity strength. Negative affinity is a type modifier that indicates that the given IDs should be avoided, and affinity of the specified type should be set to all other processors in the system. .sp .LP When querying affinities, \fBPA_TYPE_CPU\fR, \fBPA_TYPE_PG\fR , or \fBPA_TYPE_LGRP\fR may be specified as an indication that the returned identifiers must be either those of CPUs, processor groups or locality groups that contain the processors to which the specified LWPs have affinity for. If no type is specified, the interface defaults to CPUs. .sp .LP Upon a successful query, \fBnids\fR will contain the number of CPUs, PGs or LGRPs that the specified LWPs has affinity for. If \fBids\fR is not NULL, \fBprocessor_affinity\fR will store, up to the initial \fBnids\fR value, the IDs of the indicated type. Additionally, flags will return the affinity strength and whether any type of inheritance is excluded. .sp .LP When clearing affinities, the caller can either specify a set of LWPs that should have their affinities revoked (through the \fBps\fR argument) or none, and instead specify a list of CPU, PG or LGRP identifiers for which all affinities must be cleared. See EXAMPLES below for details. .sp .LP Querying, clearing and setting affinities are mutually exclusive operations. Combining such flags results in failure and \fBerrno\fR set to \fBEINVAL\fR. .sp .LP It is important to note that the runtime behavior determined by \fBprocessor_affinity\fR is subject to the continued online state of the specified CPUs and their affiliation to the same processor set as the target LWPs. If these underlying conditions change, a LWP will lose its affinity for a given CPU and will need to be reset once the conditions are restored. .sp .LP When specifying multiple LWPs, these should all be bound to the same processor set (or to none), as LWPs can only have affinity for CPUs contained in their set. Additionally, setting affinities will succeed if \fBprocessor_affinity\fR is able to set a LWPs affinity for any of the specified processors, even if a subset of such CPUs may be invalid, offline, or faulted. .sp .LP \fBprocessor_bind\fR and \fBprocessor_affinity\fR are implemented by the same mechanism, only differing in the limitations imposed by the number and types of arguments each accepts. This is to say that calls to \fBprocessor_bind\fR are essentially calls to \fBprocessor_affinity\fR that only allow setting and querying binding to a single CPU at a time. .sp .LP The \fB{PRIV_PROC_OWNER}\fR privilege must be asserted in the effective set of the calling process or the real or effective user ID of the calling process must match the real or effective user ID of the LWPs being bound. If the calling process does not have permission to change all of the specified LWPs, the bindings of the LWPs for which it does have permission will be changed even though an error is returned. .SH RETURN VALUES .sp .LP \fBprocessor_affinity\fR(2) returns \fB0\fR upon successful completion. If an error occurs, \fB-1\fR is returned and \fBerrno\fR is set to indicate its cause. .sp .ne 2 .mk .na \fB\fB0\fR\fR .ad .RS 6n .rt Returns \fB0\fR upon successful completion. .RE .sp .ne 2 .mk .na \fB\fB-1\fR\fR .ad .RS 6n .rt Returns \fB-1\fR upon an error and \fBerrno\fR is set to indicate the cause. .RE .SH ERRORS .sp .LP The \fBprocessor_affinity()\fR function will fail if the following error codes are returned: .sp .ne 2 .mk .na \fB\fBESRCH\fR\fR .ad .RS 10n .rt None of the specified LWPs exist. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt The contents of \fBps\fR are invalid, one or more CPUs specified through \fBnids\fR and \fBids\fR are offline, faulted, part of different processor sets, or the given combination of flags is invalid. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 10n .rt The location pointed to by \fBps\fR, \fBnids\fR, \fBids\fR or \fBflags\fR could not be accessed. .RE .sp .ne 2 .mk .na \fB\fBEPERM\fR\fR .ad .RS 10n .rt The \fB{PRIV_PROC_OWNER}\fR privilege is not asserted in the effective set of the calling process and its real or effective user ID does not match the real or effective user ID of one of the LWPs being bound. .RE .SH EXAMPLES .LP \fBExample 1 \fRSetting Strong Affinity for CPUs [0-3] to the Current LWP .LP .nf #include #include #include .fi .sp .in +2 .nf procset_t ps; uint_t nids = 4; id_t ids[4] = { 0, 1, 2, 3 }; uint32_t flags = PA_TYPE_CPU | PA_AFF_STRONG; setprocset(&\fBps\fR, \fBPOP_AND\fR, \fBP_PID\fR, \fBP_MYID\fR, \fBP_LWPID\fR, \fBthr_self()\fR); if (processor_affinity(&\fBps\fR, &\fBnids\fR, ids, &\fBflags\fR) != 0) { fprintf(stderr, "Error setting affinity.\n"); perror(NULL); } .fi .in -2 .LP \fBExample 2 \fRSetting Weak Affinity for CPUs in Processor Group 3 and 7 to Process 300's LWP 2 .LP .nf #include #include #include .fi .sp .in +2 .nf procset_t ps; uint_t nids = 4; id_t ids[4] = { 3, 7 }; uint32_t flags = PA_TYPE_PG | PA_AFF_WEAK; setprocset(&\fBps\fR, \fBPOP_AND\fR, \fBP_PID\fR, 300, \fBP_LWPID\fR, 2); if (processor_affinity(&\fBps\fR, &\fBnids\fR, ids, &\fBflags\fR) != 0) { fprintf(stderr, "Error setting affinity.\n"); perror(NULL); } .fi .in -2 .LP \fBExample 3 \fRSetting Negative Strong Negative Affinity for all CPUs in \fBlgroup\fR 12 to All of User 323's Processes That Are Running Inside \fBZone 7\fR .LP .nf #include #include #include .fi .sp .in +2 .nf procset_t ps; uint_t nids = 4; id_t ids[4] = { 12 }; uint32_t flags = PA_TYPE_LGRP | PA_AFF_STRONG | PA_NEGATIVE; setprocset(&\fBps\fR, POP_AND, P_UID, 323, P_ZONEID, 7); if (processor_affinity(&\fBps\fR, &\fBnids\fR, ids, &\fBflags\fR) != 0) { fprintf(stderr, "Error setting affinity.\n"); perror(NULL); } .fi .in -2 .LP \fBExample 4 \fRClearing Affinities of the Current Process .LP .nf #include #include #include .fi .sp .in +2 .nf procset_t ps; uint32_t flags = PA_CLEAR; setprocset(&\fBps\fR, POP_AND, P_PID, P_MYID, P_ALL, 0); if (processor_affinity(&\fBps\fR, NULL, NULL, &\fBflags\fR) != 0) { fprintf(stderr, "Error clearing affinity.\n"); perror(NULL); } .fi .in -2 .LP \fBExample 5 \fRClearing All Affinities for CPUs 5 and 7 .LP .nf #include #include #include .fi .sp .in +2 .nf uint_t nids = 2; id_t ids[4] = { 5, 7 }; uint32_t flags = PA_CLEAR | PA_TYPE_CPU; if (processor_affinity(NULL, &\fBnids\fR, ids, &\fBflags\fR) != 0) { fprintf(stderr, "Error clearing affinity.\n"); perror(NULL); } .fi .in -2 .LP \fBExample 6 \fRQuerying and Printing Affinities for the Current LWP .LP .nf #include #include #include .fi .sp .in +2 .nf procset_t ps; uint_t nids; id_t *ids; uint32_t flags = PA_QUERY; int i; setprocset(&\fBps\fR, POP_AND, P_PID, P_MYID, P_LWPID, thr_self()); if (processor_affinity(&\fBps\fR, &\fBnids\fR, NULL, &\fBflags\fR) != 0) { fprintf(stderr, "Error querying number of ids.\n"); perror(NULL); } else { fprintf(stderr, "LWP %d has affinity for %d CPUs.\n", thr_self(), nids); } flags = PA_QUERY; ids = calloc(nids, sizeof (id_t)); if (processor_affinity(&\fBps\fR, &\fBnids\fR, ids, &\fBflags\fR) != 0) { fprintf(stderr, "Error querying ids.\n"); perror(NULL); } if (nids == 0) printf("Current LWP has no affinity set.\n"); else printf("Current LWP has affinity for the following CPU(s):\n"); for (i = 0; i < nids; i++) printf(" %u", ids[i]); printf("\n"); .fi .in -2 .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBpsrinfo\fR(1M), \fBpsradm\fR(1M), \fBpsrset\fR(1M), \fBpginfo\fR(1M), \fBprocessor_info\fR(2), \fBprocessor_bind\fR(2), \fBpset_create\fR(2), \fBpset_bind\fR(2), \fBexec\fR(2), \fBfork\fR(2), \fBthr_create\fR(3C), \fBprocset.h\fR(3HEAD), \fBattributes\fR(5), \fBprivileges\fR(5)