HP OpenVMS System Services Reference Manual
Each pair of bits in the access mode vector represents the access mode
for the specific type of access. For example, bits <6:7>
represent the access mode value used to check for delete access.
CHP$_OBJECT_CLASS
A character string containing the protected object class associated
with the object. The object class string is used to determine whether
any security auditing is enabled for the object access event. This item
code is required when the CHP$_AUDIT flag is specified.
CHP$_OBJECT_NAME
A character string containing the object name associated with the
protection check. The object name string is included in any resulting
security audit. If an object name string is not specified, the string
"<not available>" is substituted in any security audit
for all protected object classes other than FILE. For FILE class
audits, it is assumed that the caller has supplied an object name by
using the auditing item list (NSA$_OBJECT_NAME).
CHP$_OWNER
A longword describing the object's owner identifier (UIC or general
identifier). This might be either a UIC format identifier or a general
identifier.
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.
|
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 a 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.
Usually, $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.
|
$CLEAR_SYSTEM_EVENT (Alpha and I64)
Removes one or more notification requests previously established by a
call to $SET_SYSTEM_EVENT.
This service does not allow you to specify a handle and an event. You
must pass a zero as one of these parameters. You can either clear by
handle or request that all events for the user be cleared.
Format
SYS$CLEAR_SYSTEM_EVENT [handle] ,[acmode] ,event
C Prototype
int sys$clear_system_event (struct _generic_64 * 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 cleared. The
handle argument uniquely identifies the request and is
returned when the $SET_SYSTEM_EVENT service is called. The
handle argument may be omitted by specifying a zero
address.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode of the system event to be cleared. The
acmode argument is a longword containing the access
mode. The value of the access mode is maximized with the access mode of
the caller.
event
| OpenVMS usage: |
event_code |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The event argument is a value indicating the type of
system event to be cleared. SYSEVT$C_ALL_EVENTS may be specified to
clear all event types.
Description
The Clear System Event service removes one or more event types or
notification objects previously established by a call to the
$SET_SYSTEM_EVENT service.
A valid request specifies either the handle for a
specific notification request, or is a wildcard clear of all
notification objects whose is access mode is greater than or equal to
acmode.
If the handle argument is specified, caller's access
mode must be less than or equal to the access mode of the object to be
cleared.
If SYSEVT$C_ALL_EVENTS is specified, or the set of events enabled for
the object(s) becomes empty, the notification object is deleted.
Required Access or Privileges
None
Required Quota
None
Related Services
$SET_SYSTEM_EVENT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The service cannot access the location specified by the handle.
|
|
SS$_BADPARAM
|
One or more arguments has an invalid value, such as an invalid handle.
|
|
SS$_NOSUCHOBJ
|
No request was found that matches the description supplied.
|
$CLEAR_UNWIND_TABLE (I64 Only)
Clears unwind table (UT) information.
Format
SYS$CLEAR_UNWIND_TABLE code_base_va
C Prototype
int SYS$CLEAR_UNWIND_TABLE (unsigned __int64 code_base_va);
Arguments
code_base_va
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Input by value. Must be the process virtual address of the start of a
registered code range.
Description
Clears (removes) the indicated registration. Error status returned on
bad code_base_va or insufficient access mode.
Required Access or Privileges
The unwind table information that corresponds to code_base_va will be
removed only if it was registered in a mode equal to or less privileged
than the caller of $CLEAR_UNWIND_TABLE.
Required Quota
None
Related Services
SYS$SET_UNWIND_TABLE, SYS$GET_UNWIND_ENTRY_INFO. Also see
LIB$GET_UIB_INFO in HP OpenVMS Calling Standard.
Condition Values Returned
|
SS$_NORMAL
|
Routine completed successfully.
|
|
SS$_IVAADDR
|
code_base_va not registered.
|
|
SS$_IVACMODE
|
Insufficient access mode.
|
$CLOSE
The Close service terminates file processing and closes the file. This
service performs an implicit Disconnect service for all record streams
associated with the file.
For additional information about this service, see the OpenVMS Record Management 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.
|
|
