OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

Note

CHP$_OWNER is used in conjunction with the CHP$_PROT item code.

CHP$_PRIV

A quadword that defines an accessor's privilege mask. Each bit in the mask has a symbolic name, defined by the $PRVDEF macro. You form the bit array by specifying the symbolic name of each privilege in a logical OR operation. See the $SETPRV system service for the symbolic name and description of each privilege.

CHP$_PRIVUSED

A longword mask of flags representing privileges used to gain the requested access.

You can also obtain the values as masks with the appropriate bit set by using the prefix CHP$M rather than CHP$V. The symbols are defined in the system macro library ($CHPDEF). The following symbols are used as offsets to the bits within the longword.

Symbol Meaning

CHP$V_SYSPRV SYSPRV was used to gain the requested access.

CHP$V_GRPPRV GRPPRV was used to gain the requested access.

CHP$V_BYPASS BYPASS was used to gain the requested access.

CHP$V_READALL READALL was used to gain the requested access.

CHP$V_OPER OPER was used to gain the requested access.

CHP$V_GRPNAM GRPNAM was used to gain the requested access.

CHP$V_SYSNAM SYSNAM was used to gain the requested access.

CHP$V_GROUP GROUP was used to gain the requested access.

CHP$V_WORLD WORLD was used to gain the requested access.

CHP$V_PRMCEB PRMCEB was used to gain the requested access.

CHP$V_UPGRADE UPGRADE was used to gain the requested access.

CHP$V_DOWNGRADE DOWNGRADE was used to gain the requested access.

Symbol	Meaning
CHP$V_SYSPRV	SYSPRV was used to gain the requested access.
CHP$V_GRPPRV	GRPPRV was used to gain the requested access.
CHP$V_BYPASS	BYPASS was used to gain the requested access.
CHP$V_READALL	READALL was used to gain the requested access.
CHP$V_OPER	OPER was used to gain the requested access.
CHP$V_GRPNAM	GRPNAM was used to gain the requested access.
CHP$V_SYSNAM	SYSNAM was used to gain the requested access.
CHP$V_GROUP	GROUP was used to gain the requested access.
CHP$V_WORLD	WORLD was used to gain the requested access.
CHP$V_PRMCEB	PRMCEB was used to gain the requested access.
CHP$V_UPGRADE	UPGRADE was used to gain the requested access.
CHP$V_DOWNGRADE	DOWNGRADE was used to gain the requested access.

CHP$_PROT

A vector describing the object's SOGW protection mask. The following diagram depicts the format for describing the object's protection.

The first word contains the first four protection bits for each field, the second word the next four protection bits, and so on. If a bit is clear, access is granted. By convention, the first five protection bits are (from right to left in each field of the first word) read, write, execute, delete, and (in the low-order bit in each field of the second word) control access. You can specify the CHP$_PROT item in increments of words; if a short buffer is given, zeros are assumed for the remainder.

The $CHKPRO service compares the low-order four bits of CHP$_ACCESS against one of the 4-bit fields in the low-order word of CHP$_PROT, the next four bits of CHP$_ACCESS against one of the 4-bit fields in the next word of CHP$_PROT, and so on. The $CHKPRO service chooses a field of CHP$_PROT based on the privileges specified for the accessor (CHP$_PRIV), the UICs of the accessor (CHP$_RIGHTS or CHP$_ADDRIGHTS, or both), and the object's owner (CHP$_OWNER).

You must also specify the identifier of the object's owner with CHP$_OWNER when you use CHP$_PROT.

CHP$_RIGHTS

A vector that points to an accessor's rights list. The accessor's UIC is the identifier of the first entry in the rights list. The accessor's rights list consists of the rights list specified by CHP$_RIGHTS and, optionally, the rights list specified by the CHP$_ADDRIGHTS item codes.

CHP$_UIC

A longword specifying the accessor's owner UIC. This item code can be used to avoid having to pass an entire rights list segment via the CHP$_RIGHTS item code. If CHP$_RIGHTS and then CHP$_UIC are specified, in that order, $CHKPRO initializes the local rights list and then replaces just the owner UIC with the value of CHP$_UIC.

Description

The Check Access Protection service determines whether an accessor with the specified rights and privileges can access an object with the specified attributes. The service invokes the system's access protection check, which permits layered products and other subsystems to build protected structures that are consistent with the protection facilities provided by the base operating system. The service also allows a privileged subsystem to perform protection checks on behalf of a requester.
If the accessor can access the object, $CHKPRO returns the SS$_NORMAL status code; otherwise, $CHKPRO returns SS$_NOPRIV.
The item list arguments accepted by this service permit you to specify the protection of the object being accessed, the rights and privileges of the accessor, and the type of access desired.
At minimum, the following item codes should be specified to perform a third-party protection check:

CHP$_ACCESS
CHP$_OWNER
CHP$_PRIV
CHP$_PROT
CHP$_UIC

The default for information relating to the subject is to use the current process information (for example, privileges). The default for missing object information is a representation of 0.
The caller can also request that an object access audit be performed if security auditing has been enabled for the object class or if auditing ACEs are contained in the object's ACL. The CHP$V_AUDIT flag requests an access audit. This requires that the caller be in executive or kernel mode or possess the AUDIT privilege.
Normally, $CHKPRO generates an object access audit when an audit is required. The caller can specify the CHP$V_CREATE flag to force an object creation audit instead of an object access audit. Similarly, the CHP$V_DELETE flag forces an object deletion audit. The CHP$_AUDIT_LIST item code can be used to specify additional information to be included in any resulting audit records.
Required Access or Privileges

AUDIT privilege is required when requesting an audit.
Required Quota

None
Related Services

$AUDIT_EVENT, $CHECK_ACCESS, $CREATE_USER_PROFILE, $FORMAT_ACL

Condition Values Returned

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

SS$_ACCVIO The item list cannot be read by the caller, or one of the buffers specified in the item list cannot be written by the caller.

SS$_ACLFULL More than 20 CHP$_ACL items were given.

SS$_BADPARAM The argument is invalid.

SS$_BUFFEROVF The output buffer is too small and the protection check succeeded.

SS$_IVACL You supplied an invalid ACL segment with the CHP$_ACL item.

SS$_IVBUFLEN The output buffer is too small and the protection check failed.

SS$_NOAUDIT Caller lacks privilege to request audit.

SS$_NOPRIV The desired access is not granted.

SS$_RIGHTSFULL More than 11 CHP$_ADDRIGHTS items were given.

$CLRCLUEVT

Removes one or more notification requests previously established by a call to SYS$SETCLUEVT.

Format

SYS$CLRCLUEVT [handle] ,[acmode] ,[event]

C Prototype

int sys$clrcluevt (struct _cluevthndl *handle, unsigned int acmode, unsigned int event);

Arguments

handle

OpenVMS usage: identifier

type: quadword (unsigned)

access: read only

mechanism: by reference

Identification of the AST request to be canceled. The handle argument uniquely identifies the request and is returned when the $SETCLUEVT service is called.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode of the cluster configuration event to be canceled. The acmode argument is a longword containing the access mode.
Each access mode has a symbolic name. The $PSLDEF macro defines the following symbols for the four access types.

Symbol Access Mode

PSL$C_KERNEL Kernel

PSL$C_EXEC Executive

PSL$C_SUPER Supervisor

PSL$C_USER User

event

OpenVMS usage: event_code

type: longword (unsigned)

access: read only

mechanism: by value

Event code indicating the type of cluster configuration event for which an AST is no longer to be delivered. The event argument is a value indicating which type of event is no longer of interest.
Each event type has a symbolic name. The $CLUEVTDEF macro defines the following symbolic names.

Symbolic Name Description

CLUEVT$C_ADD One or more OpenVMS nodes have been added to the OpenVMS Cluster system.

CLUEVT$C_REMOVE One or more OpenVMS nodes have been removed from the OpenVMS Cluster system.

Symbol	Access Mode
PSL$C_KERNEL	Kernel
PSL$C_EXEC	Executive
PSL$C_SUPER	Supervisor
PSL$C_USER	User

Symbolic Name	Description
CLUEVT$C_ADD	One or more OpenVMS nodes have been added to the OpenVMS Cluster system.
CLUEVT$C_REMOVE	One or more OpenVMS nodes have been removed from the OpenVMS Cluster system.

Description

The Clear Cluster Event service removes one or more notification requests previously established by a call to the $SETCLUEVT service. $CLRCLUEVT verifies that the parameters specify a valid request, and dequeues and deallocates the request.
A valid request specifies either the handle argument or the event argument. If the handle argument is specified, the acmode argument must match the value recorded when $SETCLUEVT was called. If the event argument is specified, all requests matching the access mode are canceled, provided that the access mode is not greater than the caller's mode. If the access mode parameter is more privileged than the mode of the caller, the mode of the caller will be used.
Required Access or Privileges

None
Required Quota

None
Related Services

$SETCLUEVT, $TSTCLUEVT

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADPARAM There is an unsatisfactory combination of event and handle parameters, or the event was specified incorrectly.

SS$_NOSUCHOBJ No request was found that matches the description supplied.

$CLREF

Clears (sets to 0) an event flag in a local or common event flag cluster.

Format

SYS$CLREF efn

C Prototype

int sys$clref (unsigned int efn);

Argument

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag to be cleared. The efn argument is a longword containing this number; however, $CLREF uses only the low-order byte.

Condition Values Returned

SS$_WASCLR The service completed successfully. The specified event flag was previously 0.

SS$_WASSET The service completed successfully. The specified event flag was previously 1.

SS$_ILLEFC You specified an illegal event flag number.

SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

$CMEXEC

Changes the access mode of the calling process to executive mode.

Format

SYS$CMEXEC routin ,[arglst]

C Prototype

int sys$cmexec (int (*routin)(__unknown_params), unsigned int *arglst);

Arguments

routin

OpenVMS usage: procedure

type: procedure value

access: call without stack unwinding

mechanism: by reference

Routine to be executed while the process is in executive mode. The routin argument is the address of this routine.
arglst

OpenVMS usage: arg_list

type: longword (unsigned)

access: read only

mechanism: by reference

Argument list to be passed to the routine specified by the routin argument. The arglst argument is the address of this argument list.
If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a value of 0 in the arglst argument. This means that the arglst argument must contain an accessible virtual address for an argument list, the first longword of which must be a valid list size.

Description

The Change to Executive Mode service allows a process to change its access mode to executive, execute a specified routine, and then return to the access mode in effect before the call was issued.
The $CMEXEC service uses standard procedure calling conventions to pass control to the specified routine.
On Alpha systems, to conform to the OpenVMS calling standard, you must not omit the arglst argument.
On VAX systems, if no argument list is specified, the argument pointer (AP) contains a 0. However, to conform to the OpenVMS calling standard, you must not omit the arglst argument.
On Alpha and VAX systems, when you use the $CMEXEC service, the system service dispatcher modifies the registers before entry into the target routine. The specified routine must exit with a RET instruction and should place a status value in R0 before returning.
All of the Change Mode system services are intended to allow for the execution of a routine at an access mode more (not less) privileged than the access mode from which the call is made. If $CMEXEC is called while a process is executing in kernel mode, the routine specified by the routin argument executes in kernel mode, not executive mode.
Required Access or Privileges

To call this service, the process must either have CMEXEC or CMKRNL privilege or be currently executing in executive or kernel mode.
Required Quota

None
Related Services

None

Condition Values Returned

SS$_ACCVIO The arglst or routine argument is not accessible.

SS$_BADPARAM The routine specified is in a translated image.

SS$_NOPRIV The process does not have the privilege to change mode to executive.

All other values The routine executed returns all other values.

$CMEXEC_64 (Alpha Only)

On Alpha systems, changes the access mode of the calling process to executive mode.
This service accepts 64-bit addresses.

Format

SYS$CMEXEC_64 routin_64 ,arglst_64

C Prototype

int sys$cmexec_64 (int (*routin_64)(__unknown_params), unsigned __int64 *arglst_64);

Arguments

routin_64

OpenVMS usage: procedure

type: procedure value

access: call without stack unwinding

mechanism: by 32- or 64-bit reference

Routine to be executed while the process is in executive mode. The routin_64 argument is the 32- or 64-bit address of this routine.
arglst_64

OpenVMS usage: arg_list

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Argument list to be passed to the routine specified by the routin_64 argument. The arglst_64 argument is the 32- or 64-bit address of this argument list.
If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a value of 0 in the arglst_64 argument. This means that the arglst_64 argument, if nonzero, must contain an accessible virtual address for an argument list, the first quadword of which must be a number between 0 and 255 specifying the number of quadwords that follow it on the list.

Description

The Change to Executive Mode with Quadword Argument List service allows a process to change its access mode to executive, execute a specified routine, and then return to the access mode in effect before the call was issued.
The $CMEXEC_64 service uses standard procedure-calling conventions to pass control to the specified routine.
When you use the $CMEXEC_64 service, the system modifies the registers before entry into the target routine. The specified routine must exit with a RET instruction.
All of the Change Mode system services are intended to allow for the execution of a routine at an access mode more (not less) privileged than the access mode from which the call is made. If $CMEXEC_64 is called while a process is executing in kernel mode, the routine specified by the routin_64 argument executes in kernel mode, not executive mode.
Required Access or Privileges

To call this service, the process must either have CMEXEC or CMKRNL privilege or be currently executing in executive or kernel mode.
Required Quota

None
Related Services

$CMEXEC, $CMKRNL, $CMKRNL_64

Condition Values Returned

SS$_ACCVIO The arglst argument or routine is not accessible.

SS$_BADPARAM The routine specified is in a translated image.

SS$_NOCMEXEC The process does not have the privilege to change mode to executive.

All other values The routine executed returns all other values.

$CMKRNL

Changes the access mode of the calling process to kernel mode. This service allows a process to change its access mode to kernel, execute a specified routine, and then return to the access mode in effect before the call was issued.

Format

SYS$CMKRNL routin ,[arglst]

C Prototype

int sys$cmkrnl (int (*routin)(__unknown_params), unsigned int *arglst);

Arguments

routin

OpenVMS usage: procedure

type: procedure value

access: call without stack unwinding

mechanism: by reference

Routine to be executed while the process is in kernel mode. The routin argument is the address of this routine.
arglst

OpenVMS usage: arg_list

type: longword (unsigned)

access: read only

mechanism: by reference

Argument list to be passed to the routine specified by the routin argument. The arglst argument is the address of this argument list.
If the arglst value is nonzero and is not accessible as an address or if the routine is inaccessible, the service returns SS$_ACCVIO.
Alpha systems require a pointer to a valid argument list or a value of 0 in the arglst argument. This means that the arglst argument must contain an accessible virtual address for an argument list, the first longword of which must be a valid list size.

Description

The Change Mode to Kernel ($CMKRNL) and the Change Mode to Executive ($CMEXEC) system services provide a simple and secure path for applications to execute code in the privileged kernel and executive processor modes. These services first check for the necessary CMKRNL or CMEXEC privileges, and then call the routine specified in the argument list in the specified processor mode.
When code is executing in a privileged processor mode, such as executive or kernel mode, the code executes with full OpenVMS privileges. Furthermore, specific protection checks can also be bypassed. For example, $CMKRNL bypasses the check for CMKRNL privilege that is normally required when $CMKRNL is called from executive mode, and $SETPRV calls are processed without SETPRV privilege when called from executive or kernel mode.
The condition value returned from the procedure specified in the argument list is used as the return status from the $CMKRNL or $CMEXEC system service call. Based on the OpenVMS calling standard, this condition value is returned by register R0, using a language-specific mechanism.

Note
The $CMKRNL and $CMEXEC system services are typically used to access privileged or internal OpenVMS routines or data structures. The code to access these data structures can be OpenVMS version-dependent, particularly if the internal routines or data structures change. Errors that occur in code executing in a privileged processor mode can lead to one or more possible situations: data corruptions, process deletions, or system crashes.
The particular library routines and libraries that can be called from code executing in executive or kernel mode can also be limited, because not all library routines accessable from user mode can be called from kernel mode.

Code Example

The following code example shows how to call a specified routine in kernel mode using this service:
/* // cmkrnl.c // // OpenVMS example of calling a specified routine in kernel mode, // using the SYS$CMKRNL system service. // // Requires CMKRNL privilege. // // Errors in kernel-mode code can corrupt critical data structures, // can cause process deletions, and can potentially crash the OpenVMS // operating system. // // To build: // // $ CC/DECC CMKRNL // $ LINK CMKRNL // $ RUN CMKRNL */ #include <ssdef.h> #include <starlet.h> #include <stdio.h> #include <stdlib.h> #include <string.h> #include <stsdef.h> /* // The KernelRoutine routine executes in kernel mode, but does // absolutely nothing useful. */ int KernelRoutine( int *UsrArg1, int *UsrArg2) { return SS$_NORMAL; } main() { int RetStat; int ArgList[3]; int i = 0; printf("OpenVMS Alpha example of calling sys$cmkrnl\n"); /* // Build the routine argument list in an array -- the KernelRoutine // call expects two arguments, necessitating an array containing the // count and the two arguments. */ ArgList[++i] = 1; ArgList[++i] = 2; ArgList[0] = i; /* // Now invoke the KernelRoutine in kernel mode... */ RetStat = sys$cmkrnl( KernelRoutine, ArgList ); if (!$VMS_STATUS_SUCCESS( RetStat )) return RetStat; printf("Now successfully back in user mode.\n"); return SS$_NORMAL; }
Previous Next Contents Index

privacy and legal statement

4527PRO_009.HTML

SS$_NORMAL	The service completed successfully; the desired access is granted.
SS$_ACCVIO	The item list cannot be read by the caller, or one of the buffers specified in the item list cannot be written by the caller.
SS$_ACLFULL	More than 20 CHP$_ACL items were given.
SS$_BADPARAM	The argument is invalid.
SS$_BUFFEROVF	The output buffer is too small and the protection check succeeded.
SS$_IVACL	You supplied an invalid ACL segment with the CHP$_ACL item.
SS$_IVBUFLEN	The output buffer is too small and the protection check failed.
SS$_NOAUDIT	Caller lacks privilege to request audit.
SS$_NOPRIV	The desired access is not granted.
SS$_RIGHTSFULL	More than 11 CHP$_ADDRIGHTS items were given.

OpenVMS usage:	identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

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

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

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	There is an unsatisfactory combination of event and handle parameters, or the event was specified incorrectly.
SS$_NOSUCHOBJ	No request was found that matches the description supplied.

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

SS$_WASCLR	The service completed successfully. The specified event flag was previously 0.
SS$_WASSET	The service completed successfully. The specified event flag was previously 1.
SS$_ILLEFC	You specified an illegal event flag number.
SS$_UNASEFC	The process is not associated with the cluster containing the specified event flag.

OpenVMS usage:	procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

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

SS$_ACCVIO	The arglst or routine argument is not accessible.
SS$_BADPARAM	The routine specified is in a translated image.
SS$_NOPRIV	The process does not have the privilege to change mode to executive.
All other values	The routine executed returns all other values.

SS$_ACCVIO	The arglst argument or routine is not accessible.
SS$_BADPARAM	The routine specified is in a translated image.
SS$_NOCMEXEC	The process does not have the privilege to change mode to executive.
All other values	The routine executed returns all other values.