pset_bind(2)

NAME

pset_bind() — bind process or thread to a processor set

SYNOPSIS

#include <sys/pset.h> 

int pset_bind(
psetid()_t pset,
idtype_t idtype,
id_t id,
psetid_t *opset
);

DESCRIPTION

The pset_bind() function binds thread(s) or process(es) specified by idtype and id to the processor set pset.

If idtype is P_PID, then id specifies the pid of the process to be assigned, and the binding affects all threads of the process.

If idtype is P_LWPID, then id specifies the lwpid of the thread to be assigned, and the binding affects only the specified thread. You cannot specify a pthread ID for pthreads in id, an lwpid is required. See pthread_pset_bind_np in pthread_processor_bind_np(3T) for information on binding pthreads to processor sets.

If idtype is P_UID, then id specifies the effective user ID of all processes to be assigned, and the binding affects all threads in these processes. The operation is not a "success is all or none" type, because it rebinds as many processes as possible without error.

If idtype is P_PGID, then id specifies the process group ID of all processes to be assigned, and the binding affects all threads in these processes. The operation is not a "success is all or none" type, because it rebinds as many processes as possible without error. All processes in a process group need not have same access permissions to target processor set.

If opset is not NULL, it contains the previous processor set binding of the specified thread or process upon successful operation. However, opset is ignored if idtype is P_UID or P_PGID.

All threads of a process need not be assigned to the same processor set.

If id is P_MYID, then idtype identifies the target process(es) or thread(s) to be assigned to pset. The P_PID identifies the calling process, whereas P_LWPID identifies the calling thread. The P_UID identifies all processes with the effective user ID of the calling process, and P_PGRP identifies all processes in the process group of the calling process.

If pset is PS_DEFAULT or PS_NONE, the system default processor set is the target processor set.

If pset is PS_QUERY, the processor set binding is not changed, the current processor set's processor set ID is returned in opset. If idtype is P_UID or P_PGID, PS_QUERY request has no meaning. No special access privileges are needed for PS_QUERY operation.

If pset is the same as the current processor set for the specified process or thread, the operation is considered a PS_QUERY request.

The system daemon processes are not restricted to any user defined processor sets. They may execute on any processor in the system irrespective of the processor set configuration a user may have set up. The processor set binding of system daemon processes may not be changed. The PS_QUERY operation on system daemon processes returns a special processor set ID of PS_KERNDAEMON to indicate they are treated differently.

Note: The system daemon processes are created in the kernel for kernel activities, and not the user daemon processes that execute in user space.

A user with the PSET privilege, or a user with EXEC permission for the processor set pset may affect the binding change. The pset_setattr() and pset_getattr() functions may be used to set and query the processor set access permissions. See pset_getattr(2)).

If the thread or process being assigned to pset has binding to a processor or a locality domain in its current processor set, the binding is reassigned to a processor or locality domain in the new processor set pset.

If pset is empty (no processors are assigned as yet), the behavior of pset_bind() function depends on the value of PSET_ATTR_EMPTY attribute. The default behavior on an attempt to bind a thread or a process to an empty processor set is to fail the request.

The child process and its first thread created by a fork() or vfork() function inherits the processor set binding from the parent process. The new threads in the multi-threaded process inherits their processor set binding from the creator thread.

Security Restrictions

Some or all of the actions associated with this system call require the PSET 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.

RETURN VALUE

pset_bind() returns the following values:

0: Successful completion.
-1: Failure. errno is set to indicate the error.

ERRORS

pset_bind sets errno to one of the following values if the corresponding condition occurs.

EFAULT: The memory location pointed to by opset is not writable by the user.
EINVAL: pset is not valid.
EINVAL: idtype or id is not valid.
EINVAL: pset is empty and the current setting of processor set attributes does not allow this operation on an empty processor set.
EINVAL: The memory location pointed to by opset is NULL and the PS_QUERY operation is requested.
ENOSYS: The processor set functionality is not supported by the underlying HP-UX version.
EPERM: User does not have necessary permissions to bind a thread or a process to specified processor set.
EPERM: The specified thread or process is a system daemon.
ESRCH: The specified thread, process, user ID, or process group does not exist.

EXAMPLES

Migrate the current thread to another processor set new_pset, and retrive its current processor set in old_pset.

#include <sys/pset.h> 

int       ret; 
psetid_t  new_pset, old_pset; 

/* 
 * Initialize new_pset first. 
 * Rebind the current thread to new_pset. 
 */ 
ret = pset_bind( new_pset, P_LWPID, P_MYID, &old_pset); 
if (ret < 0) { 
    perror("pset_bind"); 
    exit(1); 
} 

pset_bind(2)

Technical documentation

» Table of Contents

» Index