ra_exec Subroutine

Purpose

Executes a file and attaches it to a given resource.

Library

Standard C library (libc.a)

Syntax

#include <sys/rset.h>
int ra_execl(rstype, rsid, flags, path, argument0 [,argument1,...], 0)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
const char * path, argument0, argument1,...;
int ra_execle(rstype, rsid, flags, path, argument0[,argument1,...], 0, envptr)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
const char * path, argument0, argument1,...;
char * const envptr[];
int ra_execlp(rstype, rsid, flags, File, argument0[,argument1,...], 0)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
const char * File, argument0, argument1,...;
int ra_execv (rstype, rsid, flags, path, argumentv)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
const char * path;
char * const argumentv[];
int ra_execve (rstype, rsid, flags, path, argumentv, envptr)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
const char * path;
char * const argumentv[], envptr[];
int ra_execvp (rstype, rsid, flags, File, argumentv)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
const char * File;
char * const argumentv[];
int ra_exect(rstype, rsid, flags, path, argumentv, envptr)
rstype_t rstype;
rsid_t rsid;
unsigned int flags;
char * path, argumentv, envptr[];

Description

The ra_exec subroutine in all its forms, executes a new program in the calling process, and attaches the process to the resource specified by the rstype and rsid parameters. The ra_exec subroutine can attach the new process to a resource set (rstype R_RSET) or to an sradid (rstype R_SRADID).

The following conditions must be met to successfully attach a process to a resource set:
  • The resource set must contain processors that are available in the system.
  • The process must either have root authority or have CAP_NUMA_ATTACH capability.
  • The calling thread must not have a bindprocessor binding to a processor.
  • The resource set must be contained in (be a subset of ) the process' partition resource set.
Note: When the exec subroutine is used, the new process image inherits its process' resource set attachments.

Dynamic Processor Deallocation and DLPAR may invalidate the processor attachment that is being specified. A program must become DLPAR Aware to resolve this problem.

The flags parameter can be set to indicate the policy for using the resources contained in the resource set specified in the rset parameter. The only supported scheduling policy is R_ATTACH_STRSET, which is useful only when the processors of the system are running in simultaneous multithreading mode. Processors like the POWER5 support simultaneous multithreading, where each physical processor has two execution engines, called hardware threads. Each hardware thread is essentially equivalent to a single processor, and each is identified as a separate processor in a resource set. The R_ATTACH_STRSET flag indicates that the process is to be scheduled with a single-threaded policy; namely, that it should be scheduled on only one hardware thread per physical processor. If this flag is specified, then all of the available processors indicated in the resource set must be of exclusive use (the processor must belong to some exclusive use processor resource set). A new resource set, called an ST resource set, is constructed from the specified resource set and attached to the process according to the following rules:
  • All offline processors are ignored.
  • If all the hardware threads (processors) of a physical processor (when running in simultaneous multithreading mode, there will be more than one active hardware thread per physical processor) are not included in the specified resource set, the other processors of the processor are ignored when constructing the ST resource set.
  • Only one processor (hardware thread) resource per physical processor is included in the ST resource set.

Parameters

The ra_exec subroutine has the same parameters as the exec subroutine, with the addition of the following new parameters:

Item Description
rstype Specifies the type of resource the new process image will be attached to. This parameter must be one of the following:
  • R_RSET: resource set
  • R_SRADID: sradid
rsid Identifies the resource the new process image will be attached to:
  • Resource set handle (for rstype R_RSET): set the rsid.at_rset field to the desired resource set.
  • SRADID (Scheduler Resource Allocation Domain Identifier for rstype R_SRADID): set the rsid.at_sradid field to the desired sradid.
flags Specifies the policy to use for the process. For rstype R_RSET, the R_ATTACH_STRSET flag indicates that the process is to be scheduled with a single-threaded policy (only on one hardware thread per physical processor). All other flag bits are reserved and must be specified as 0.

Return Values

The ra_exec subroutine's return values are the same as the exec subroutine's return values.

Error Codes

The ra_exec subroutine's error codes are the same as the exec subroutine's error codes, with the addition of the following error codes:

Item Description
EINVAL One of the following is true:
  • The rstype parameter contains an invalid type identifier.
  • The flags parameter contains an invalid flags value.
  • The R_ATTACH_STRSET flags parameter is specified and one or more processors in the rset parameter are not assigned for exclusive use.
ENODEV The resource set specified by the rset parameter does not contain any available processors, or the R_ATTACH_STRSET flags parameter is specified and the constructed ST resource set does not have any available processors.
ENODEV An invalid rsid SRADID is specified.
EFAULT Invalid address.
EPERM One of the following is true:
  • The calling process has neither root authority nor CAP_NUMA_ATTACH attachment privilege.
  • The calling process contains one or more threads with a bindprocessor processor binding.
  • The specified resource set is not included in the calling process' partition resource set.
ENOTSUP An attempt to attach an SRADID is made and ENHANCED_AFFINITY is disabled.