processor_bind(2)

processor_bind -- bind or unbind to a processor

Synopsis

   #include <sys/types.h>
   #include <sys/procset.h>
   #include <sys/processor.h>
   
   int processor_bind(idtype_t idtype, id_t id,
   	processorid_t processorid, processorid_t *obind);

Description

The processor_bind call binds a process (or one or more Light-Weight Processes) to a specific processor.

idtype specifies whether the id argument is the Light Weight Process ID (LWP ID) for a single LWP within the caller's process, or a process ID (PID). If id is a PID, then the operation applies to all the LWPs associated with the given process. To bind or unbind a process or LWP, the real or effective user ID of the caller must match the real or saved user ID [from exec(2)] of the process being bound or unbound, or the caller must have the P_OWNER privilege.

processorid is the ID of a processor to which the given PID or LWP ID is to be bound.

If obind is not NULL, it points to a variable in which the previous binding is returned.

The valid values for idtype and corresponding interpretations of id are as follows:

P_PID: id is a process ID. The operation shall apply to all LWPs currently associated with the specified process (if any).
P_LWPID: id is an LWP ID specifying a single LWP, within the same process as the caller, to which the operation shall apply.

When the process identified by id has been bound, it will execute only on the processor specified by processorid (even if other processors are available), except briefly, if the process requires a resource that only another processor can provide. The processor may continue to run other processes. in addition to the one specified by id. The processor_bind call will fail if the process specified by id is bound exclusively to another processor or if there are already processes exclusively bound to the processor specified by processorid.

The processor_bind call is not guaranteed to be synchronous with the binding operation. If the binding operation cannot be completed immediately, the call may return before the operation completes. Any delay between the return of the function and the completion of the operation will, typically, be of very short duration.

If processorid is PBIND_NONE, the specified process is unbound; that is, it is made free to run on any processor.

Using a processorid of PBIND_QUERY queries the binding of a process without changing it. This action requires P_OWNER privilege if the target process UID does not match.

If the process specified by id is already bound to a different processor, the binding for that process will be changed to the processor specified by processorid. If obind is not NULL and the process is currently bound to a processor, that processorid is returned by obind.

The processor binding is inherited by any children created by a fork(2) call, or _lwp_create(2), and does not change across a call to exec(2).

Return values

On success, processor_bind returns 0. if obind is not NULL, the previous binding of the specified LWP shall be returned in the location pointed to by obind. If obind is not NULL and idtype and id specify a PID with more than one associated LWP, the previous binding shall be returned for a random LWP within the specified set. The previous binding shall be the processor ID of the processor to which the LWP was bound, or PBIND_NONE if the LWP was previously unbound.

On failure, processor_bind returns a negative value and sets errno to identify the error.

Errors

In the following conditions, processor_bind fails and sets errno to:

EPERM: The calling process does not have P_OWNER privilege.
EINVAL: An invalid idtype or processorid was specified, or the specified processor is currently offline.
ESRCH: None of the specified LWPs exist or idtype was P_LWPID and id specified an LWP that was not within the caller's process.
EBUSY: The process specified by id is bound exclusively to another processor or there are already processes or LWPs exclusively bound to the processor specified by processorid.
EFAULT: obind is not NULL and points to an invalid address.
EIO: The specified processor is not operational.

References

pbind(1M), pexbind(1M)

Notices

Considerations for lightweight processes

In addition to binding processes to a processor, the P_LWPID ``idtype'' (see DESCRIPTION) can be used by a process to bind individual LWPs in that process. There is no way for a process to bind LWPs in another process.