 |
OpenVMS System Services Reference Manual
$CLRAST
Clears the "AST active" status.
This enables delivery of asynchronous system traps (ASTs) for the
access mode from which the service call was issued, while an AST
routine is active.
Note
The explicit use of $CLRAST is strongly discouraged, as it complicates
synchronization issues and may lead to the unbounded consumption of
stack space.
|
Format
SYS$CLRAST
Arguments
None.
Description
Normally, AST delivery for a particular access mode is deferred while
an AST routine is executing in that access mode. When the AST routine
returns, an implicit call is made to $CLRAST to re-enable AST delivery.
Explicitly calling $CLRAST within an AST routine allows the delivery of
ASTs for the access mode from which the service call was issued, prior
to completion of the active AST routine.
Required Access or Privileges
None
Required Quota
None
Related Services
$SETAST
Condition Values Returned
|
None
|
The return value is undefined.
|
$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.
|
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. Note that this is also the same value as SS$_NORMAL.
|
|
SS$_WASSET
|
The service completed successfully. The specified event flag was
previously 1. Note that while the message id is the same as SS$_ACCVIO,
the severity bits are different.
|
|
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 accessible 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;
}
|
Required Access or Privileges
To call the $CMKRNL service, a process must either have CMKRNL
privilege or be currently executing in executive or kernel mode.
Required Quota
None
Related Services
$CMEXEC, $CMEXEC_64, $CMKRNL_64, $SETPRV
Condition Values Returned
|
SS$_ACCVIO
|
The
arglst argument or routine is not accessible.
|
|
SS$_BADPARAM
|
The routine specified is in a translated image.
|
|
SS$_NOCMKRNL
|
The process does not have the privilege to change mode to kernel.
|
|
All other values
|
The routine executed returns all other values.
|
$CMKRNL_64 (Alpha Only)
On Alpha systems, 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.
This service accepts 64-bit addresses.
Format
SYS$CMKRNL_64 routin_64 ,arglst_64
C Prototype
int sys$cmkrnl_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 kernel 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 |
Quadword argument list to be passed to the routine specified by the
routin_64 argument. The routin_64
argument is the 32- or 64-bit address of this routine.
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 Kernel Mode with Quadword Argument List 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.
The $CMKRNL_64 service uses standard procedure calling conventions to
pass control to the specified routine.
When you use the $CMKRNL_64 service, the system modifies the registers
before entry into the target routine. The system loads R4 with the
address of the process control block (PCB). The specified routine (if
programmed in MACRO-32) must exit with a RET instruction.
Required Access or Privileges
To call the $CMKRNL_64 service, a process must either have CMKRNL
privilege or be currently executing in executive or kernel mode.
Required Quota
None
Related Services
$CMEXEC, $CMEXEC_64, $CMKRNL, $SETPRV
Condition Values Returned
|
SS$_ACCVIO
|
The
arglst argument or routine is not accessible.
|
|
SS$_BADPARAM
|
The routine specified is in a translated image.
|
|
SS$_NOCMKRNL
|
The process does not have the privilege to change mode to kernel.
|
|
All other values
|
The routine executed returns all other values.
|
|
