OpenVMS System Services Reference Manual

See the description of the $PERM_REPORT_ALIGN_FAULT service for an example of a program that can be used to enable and disable user process alignment fault reporting.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL The service completed successfully.

$PERM_REPORT_ALIGN_FAULT (Alpha Only)

On Alpha systems, initializes user process alignment fault reporting.

Format

SYS$PERM_REPORT_ALIGN_FAULT

C Prototype

int sys$perm_report_align_fault (void);

ARGUMENTS

None.

DESCRIPTION

The Report Alignment Fault service allows the user to permanently enable user process alignment fault reporting for all subsequent images.
This service reports alignment faults only in exception mode. For more information about reporting modes, see the $START_ALIGN_FAULT_REPORT service.
Image alignment fault reporting takes precedence over process alignment fault reporting. That is, if both image and process alignment fault reporting are enabled, faults are reported to the image first.
Required Access or Privileges

None
Required Quota

None
Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL The service completed successfully.

Example

/**********************************************************************/ 
/*                                                                    */ 
/* SET_ALIGN_REPORT.C                                                 */ 
/*                                                                    */ 
/*  This program can be used to permanently turn on and off           */ 
/*  alignment fault reporting for a process. After creating the       */ 
/*  executable, do:                                                   */ 
/*                                                                    */ 
/*        $ align :== $dir:set_align_report.exe                       */ 
/*        $ align on                                                  */ 
/*        $ run program        ! will generate align faults on screen */ 
/*        $ align off                                                 */ 
/*        $ run program        ! will not generate align faults       */ 
/*                                                                    */ 
/**********************************************************************/ 
 
#include <stdio> 
#include <ctype> 
#include <ssdef> 
 
 
/*                alignment fault reporting system services           */ 
extern         sys$perm_report_align_fault(), 
               sys$perm_dis_align_fault_report(); 
 
main(argc, argv) 
  int                argc; 
  char               *argv[]; 
{ 
  int                status; 
 
  /* check arguments */ 
  if (argc < 2) { 
    printf ("Insufficient arguments\n"); 
    return (40); 
  } 
 
  /* check if the argument is on or off */ 
  if ((strcmp ("ON", argv[1]) == 0) || (strcmp ("on", argv[1]) == 0)) 
    /* on, turn alignment fault reporting on for this process */ 
    status = sys$perm_report_align_fault (); 
 
  else if ((strcmp ("OFF", argv[1]) == 0) || (strcmp ("off", argv[1]) == 0)) 
    /* off, turn alignment fault reporting off for this process */ 
    status = sys$perm_dis_align_fault_report (); 
 
  else 
    return (SS$_BADPARAM); 
 
  /* return status */ 
  return (status); 
}

This example shows a program that can be used to enable and disable alignment fault reporting for a process.

$PERSONA_ASSUME

Modifies the context of the current process to match the context of a given persona. The $PERSONA_ASSUME service allows an OpenVMS process to assume the identity of another user or to discard a persona to return the process to its original state.

Format

SYS$PERSONA_ASSUME persona ,[flags]

C Prototype

int sys$persona_assume ( unsigned int *persona, unsigned int flags, unsigned int *previous);

ARGUMENTS

persona

OpenVMS usage: integer

type: longword (unsigned)

access: read

mechanism: by reference

Address of a longword in which the persona handle is expected.
If the value of the context passed is 1, then the current persona is discarded, and the state of the calling process is returned to the state that existed prior to the first call to $PERSONA_CREATE.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Flag mask specifying which Persona services options are to be employed when the persona is assumed. This argument is ignored when a persona is being discarded. The following table describes each flag.

Flag Description

IMP$M_ASSUME_SECURITY Assume access rights, UIC, authorized privileges, user name, and security audit flag.

IMP$M_ASSUME_ACCOUNT Assume OpenVMS account.

IMP$M_ASSUME_JOB_WIDE Assume the new persona, even in a multiprocess job.

Flag	Description
IMP$M_ASSUME_SECURITY	Assume access rights, UIC, authorized privileges, user name, and security audit flag.
IMP$M_ASSUME_ACCOUNT	Assume OpenVMS account.
IMP$M_ASSUME_JOB_WIDE	Assume the new persona, even in a multiprocess job.

DESCRIPTION

When assuming a persona using the IMP$M_ASSUME_SECURITY option, any previously enabled image privileges will be disabled. The caller's process will have only the privileges of the impersonated user enabled. These privileges are enabled in the Current, Process, and Authorized privilege masks.
When using IMP$M_ASSUME_SECURITY, access to the job logical name table might no longer be possible because the table is protected by the UIC of the user on whose behalf the current process was created. Also, a new access to the process' controlling terminal might fail, and the process might be in a different default resource domain for locking.
Any persona is automatically discarded and deleted upon image exit. Hence, it is not possible to permanently change the persona of a process using $PERSONA_ASSUME.
The arguments are read in caller's mode, so an invalid argument can cause an access violation to be signaled.
Required Access or Privileges

None
Required Quota

None
Related Services

$PERSONA_CREATE, $PERSONA_DELETE

Condition Values Returned

SS$_NORMAL The service completed successfully; the desired access is granted.

IMP$_NOCHJIB The Job Information Block cannot be modified.

IMP$_PERSONANONGRATA Invalid persona argument.

$PERSONA_CREATE

Creates a persona that can be assumed using the $PERSONA_ASSUME service.

Format

SYS$PERSONA_CREATE persona ,usernam ,flags

C Prototype

int sys$persona_create (unsigned int *persona, void *usrnam, unsigned int flags, unsigned int usrpro, unsigned int *itmlst);

ARGUMENTS

persona

OpenVMS usage: integer

type: longword (unsigned)

access: write

mechanism: by reference

Address of a longword into which the persona handle is written.
usrnam

OpenVMS usage: char_string

type: character coded text string

access: read only

mechanism: by descriptor - fixed-length descriptor

Name of the user to be impersonated. The usrnam argument is the address of a descriptor pointing to a character string containing the user name. The string can contain a maximum of 12 alphanumeric characters.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Flag mask specifying which Persona services options are to be employed when the persona is created. The following table describes each flag.

Flag Description

IMP$M_ASSUME_DEFPRIV Create a persona with only default privileges.

IMP$M_ASSUME_DEFCLASS Create a persona with default classification.

Flag	Description
IMP$M_ASSUME_DEFPRIV	Create a persona with only default privileges.
IMP$M_ASSUME_DEFCLASS	Create a persona with default classification.

DESCRIPTION

On calling the Create Persona service, the required information concerning the OpenVMS user specified by the usrnam argument is read from the User Authorization File and Rights database and is stored in system memory. A handle to refer to the creted persona is returned in the persona argument.
It is not possible to create a persona for a username which has been disabled.
No changes are made to the caller's process as a result of calling $PERSONA_CREATE.
Some of the $PERSONA_CREATE service executes in the caller's access mode (assumed to be user mode). An improper use of the usernam argument can cause an access violation to be signaled.
Required Access or Privileges

All calls to $PERSONA_CREATE require DETACH privilege and access to the system authorization database.
Required Quota

None
Related Services

$PERSONA_ASSUME, $PERSONA_DELETE

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The persona argument cannot be written by the caller.

SS$_NODETACH Operation requires DETACH privilege.

SS$_INSFMEM Insufficient memory

IMP$_USERDISABLED User name disabled.

Any condition value returned by the $LKWSET, $GETUAI, or, $FIND_HELD can also be returned.

$PERSONA_DELETE

Deletes a persona created using the $PERSONA_CREATE service.

Format

SYS$PERSONA_DELETE persona

C Prototype

int sys$persona_delete (unsigned int *persona);

ARGUMENTS

persona

OpenVMS usage: integer

type: longword (unsigned)

access: read

mechanism: by reference

Address of a longword in which the persona handle is expected.

DESCRIPTION

The PERSONA_DELETE service frees the resources used by the persona. No changes to the caller's process are made as a result of calling $PERSONA_DELETE.
Required Access or Privileges

None
Required Quota

None
Related Services

$PERSONA_ASSUME, $PERSONA_CREATE

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_INUSE Persona is in use; it cannot be deleted.

$PROCESS_AFFINITY (Alpha Only)

On Alpha systems, allows modification of the CPU affinity set for a specified kernel thread.
This service accepts 64-bit addresses.

Format

SYS$PROCESS_AFFINITY [pidadr] [,prcnam] [,select_mask] [,modify_mask] [,prev_mask] [,flags]

C Prototype

int sys$process_affinity ( unsigned int *pidadr, void *prcnam, struct _generic_64 *select_mask, struct _generic_64 *modify_mask, struct _generic_64 *prev_mask, struct _generic_64 *flags);

ARGUMENTS

pidadr

OpenVMS usage: process_id

type: longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Process identification (PID) of a kernel thread whose affinity mask is to be modified or returned. The pidadr argument is the 32- or 64-bit address of a longword that contains the PID.
Process selection is made through a combination of the pidadr and prcnam arguments. If neither are specified or if both have a zero value, the service operations are made to the user affinity mask of the current kernel thread of the calling process. The pidadr argument takes precedence over the prcnam argument in any circumstances where both are supplied in the service call.
prcnam

OpenVMS usage: process_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor

Process name of the process whose affinity mask is to be modified or returned. The prcnam argument is the 32- or 64-bit address of a character string descriptor pointing to the process name string. A process can be identified with a 1- to 15-character string. The service operations are made to the user affinity mask of the initial thread of the specified process.
If pidadr and prcnam are both specified, then pidadr is modified or returned and prcnam is ignored. If neither argument is specified, then the context of the current kernel thread of the calling process is modified or returned.
select_mask

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Mask specifying which bits of the specified process’ affinity mask are to be modified. The select_mask argument is the 32- or 64-bit address of a quadword bit vector wherein a bit, when set, specifies that the corresponding CPU position in the mask is to be modified.
The individual CPU bits in select_mask can be referenced by their symbolic name constants, CAP$M_CPU0 through CAP$M_CPU31. These constants (zero-relative to match system CPU IDs) specify the position in the mask quadword that correspond to the bit name. Multiple CPUs can be selected by ORing together the appropriate bits.
modify_mask

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Mask specifying the settings for those explicit affinities selected in the select_mask argument. The modify_mask argument is the 32- or 64-bit address of a quadword bit vector wherein a bit, when set, specifies that the corresponding CPU is to be added to the specified process affinity set; when clear, the corresponding CPU is to be removed from the specified process affinity set.
The bit constants CAP$M_CPU0 through CAP$M_CPU31 can be used to modify the appropriate bit position in the quadword pointed to by modify_mask. Multiple CPUs can be added to the affinity set by ORing together the appropriate bits.
To add a specific CPU to the affinity mask set, that bit position must be set in both select_mask and modify_mask. To remove a specific CPU from the affinity mask set, that bit position must be set in select_mask and clear in modify_mask.
The constant CAP$K_ALL_CPU_ADD, when specified in modify_mask, indicates that all CPUs specified in select_mask are to be added to the affinity mask set. The constant CAP$K_ALL_CPU_REMOVE indicates that all CPUs in select_mask are to be removed from the affinity mask set.
prev_mask

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

Previous CPU affinity mask for the specified kernel thread before execution of this call to $PROCESS_AFFINITY. The prev_mask argument is the 32- or 64-bit address of a quadword into which $PROCESS_AFFINITY writes the previous explicit affinity bit mask.
flags

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Options selected for affinity modification. The flags argument is a quadword bit vector wherein a bit corresponds to an option. Only the bits specified below are used; the remainder of the quadword bits are reserved and must be 0.
Each option (bit) has a symbolic name, which the $CAPDEF macro defines. The flags argument is constructed by performing a logical OR operation using the symbolic names of each desired option. The following table describes the symbolic name of each option.

Symbolic Name Description

CAP$M_FLAG_PERMANENT Indicates whether to modify the permanent process affinities in addition to the current image copy. If CAP$M_FLAG_PERMANENT is set, then both the permanent and current affinities are modified. If the flag bit is clear or flags is unspecified, then just the current image process affinities are modified.
This bit also determines which of the affinity masks are returned in prev_mask. If set, the permanent mask, used to reinitialize the current set at image rundown, is returned. If the bit is clear or the flags argument is not specified, the current running mask is returned.

CAP$M_FLAG_CHECK_CPU Determines whether the kernel thread can be left in a non-runnable state under some circumstances. No operation of this service will allow a transition from a runnable to blocked state; however, if the kernel thread is already at a blocked state, this bit determines whether the result of the operation must leave it runnable. If CAP$M_FLAG_CHECK_CPU is set or flags is unspecified, the kernel thread will be checked to ensure it can safely run on one of the CPUs in the active set; otherwise, any valid state operations on kernel threads already in a blocked state will be allowed.

CAP$M_FLAG_CHECK_CPU_ACTIVE Indicates whether a check is made to verify that all CPUs in the select mask that are about to be selected for affinity binding are in the active set. This does not apply to CPUs that are about to be cleared from the current affinity set. Unlike CAP$M_FLAG_CHECK_CPU where only a single CPU has to be valid for the condition to pass, CAP$M_FLAG_CHECK_CPU_ACTIVE requires that all CPUs in the selected set must pass the criteria.

Symbolic Name	Description
CAP$M_FLAG_PERMANENT	Indicates whether to modify the permanent process affinities in addition to the current image copy. If CAP$M_FLAG_PERMANENT is set, then both the permanent and current affinities are modified. If the flag bit is clear or flags is unspecified, then just the current image process affinities are modified. This bit also determines which of the affinity masks are returned in prev_mask. If set, the permanent mask, used to reinitialize the current set at image rundown, is returned. If the bit is clear or the flags argument is not specified, the current running mask is returned.
CAP$M_FLAG_CHECK_CPU	Determines whether the kernel thread can be left in a non-runnable state under some circumstances. No operation of this service will allow a transition from a runnable to blocked state; however, if the kernel thread is already at a blocked state, this bit determines whether the result of the operation must leave it runnable. If CAP$M_FLAG_CHECK_CPU is set or flags is unspecified, the kernel thread will be checked to ensure it can safely run on one of the CPUs in the active set; otherwise, any valid state operations on kernel threads already in a blocked state will be allowed.
CAP$M_FLAG_CHECK_CPU_ACTIVE	Indicates whether a check is made to verify that all CPUs in the select mask that are about to be selected for affinity binding are in the active set. This does not apply to CPUs that are about to be cleared from the current affinity set. Unlike CAP$M_FLAG_CHECK_CPU where only a single CPU has to be valid for the condition to pass, CAP$M_FLAG_CHECK_CPU_ACTIVE requires that all CPUs in the selected set must pass the criteria.

DESCRIPTION

The Modify Process Affinity system service, based on the arguments select_mask and modify_mask, adds or removes CPUs from the specified kernel thread's affinity mask sets. If specified, the previous affinity mask is returned in prev_mask. With the modify_mask argument, multiple CPUs can be added or removed from the process affinity mask set in the same system service call.
Adding a specific CPU to the process affinity mask indicates that the kernel thread is able to execute only on that CPU or on the others specified in the mask. Affinity scheduling takes effect as soon as the affinity mask becomes nonzero, limiting the CPU selection for the kernel thread to what is specified and available. Thread selection and execution is still subject to standard capability requirements, but only the affinity CPU set is considered when looking for an available site. When the affinity mask is cleared, all CPUs are again considered available and affinity is deactivated.
Either modify_mask or prev_mask, or both, must be specified as arguments. If modify_mask is specified, then select_mask must be specified as an argument. If modify_mask is not specified, then no modifications are made to the affinity mask for the specified kernel thread. In this case, select_mask is ignored. If prev_mask is not specified, then no previous mask is returned.
No service changes will be allowed if the specified kernel thread will transition from a runnable to blocked state. The CAP$M_FLAG_CHECK_CPU bit in the flags argument requires that the final thread state be runnable regardless of previous state; otherwise, interim changes that maintain a blocked state are allowed if the thread is already in one.
Required Privileges

The caller must have the ALTPRI privilege to call SYS$PROCESS_AFFINITY to modify its own affinity mask. To modify another process’ affinity mask, the caller must have:

ALTPRI---To modify any process with a matching UIC
ALTPRI and GROUP---To modify any process in the same UIC group
ALTPRI and WORLD---To modify any process

To call SYS$PROCESS_AFFINITY simply to retrieve the specific process or global mask, the caller need only have the following privileges:

None---To retrieve the state of itself or any process with a matching UIC
GROUP---To retrieve the state of any process in the same UIC group
WORLD---To retrieve the state of any process

Related Services

$CPU_CAPABILITIES
$PROCESS_CAPABILITIES

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADPARAM One of more arguments has an invalid value.

SS$_ACCVIO The service cannot access the locations specified by one or more arguments.

SS$_NOPRIV Insufficient privilege for attempted operation.

SS$_NOSUCHTHREAD The specified kernel thread does not exist.

SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified.

SS$_IVLOGNAM The process name string has a length of 0 or has more than 15 characters.

SS$_CPUCAP No CPU can run the specified process with new affinities.

SS$_INSFARG Fewer than the required number of arguments were specified or no operation was specified.

$PROCESS_CAPABILITIES (Alpha Only)

On Alpha systems, allows modification of the user capability set for a specified kernel thread, or for the global user capability process default.
This service accepts 64-bit addresses.

Format

SYS$PROCESS_CAPABILITIES [pidadr] [,prcnam] [,select_mask] [,modify_mask] [,prev_mask] [,flags]

C Prototype

int sys$process_capabilities (unsigned int *pidadr, void *prcnam, struct _generic_64 *select_mask, struct _generic_64 *modify_mask, struct _generic_64 *prev_mask, struct _generic_64 *flags);

ARGUMENTS

pidadr

OpenVMS usage: process_id

type: longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Process identification (PID) of a kernel thread whose user capability mask is to be modified or returned. The pidadr argument is the 32- or 64-bit address of a longword that contains the PID.
Process selection is made through a combination of the pidadr and prcnam arguments. If neither are specified or if both have a zero value, the service operations are made to the user capability mask of the current kernel thread of the calling process. The pidadr argument takes precedence over the prcnam argument where both are supplied in the service call.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P058.HTM
  OSSG Documentation
  22-NOV-1996 13:00:17.77
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

OpenVMS usage:	integer
type:	longword (unsigned)
access:	read
mechanism:	by reference

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

SS$_NORMAL	The service completed successfully; the desired access is granted.
IMP$_NOCHJIB	The Job Information Block cannot be modified.
IMP$_PERSONANONGRATA	Invalid persona argument.

OpenVMS usage:	char_string
type:	character coded text string
access:	read only
mechanism:	by descriptor - fixed-length descriptor

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The persona argument cannot be written by the caller.
SS$_NODETACH	Operation requires DETACH privilege.
SS$_INSFMEM	Insufficient memory
IMP$_USERDISABLED	User name disabled.

SS$_NORMAL	The service completed successfully.
SS$_INUSE	Persona is in use; it cannot be deleted.

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	One of more arguments has an invalid value.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_NOPRIV	Insufficient privilege for attempted operation.
SS$_NOSUCHTHREAD	The specified kernel thread does not exist.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.
SS$_IVLOGNAM	The process name string has a length of 0 or has more than 15 characters.
SS$_CPUCAP	No CPU can run the specified process with new affinities.
SS$_INSFARG	Fewer than the required number of arguments were specified or no operation was specified.