Retrieves the security characteristics of an object.
Format
SYS$GET_SECURITY [clsnam] ,[objnam] ,[objhan] ,[flags]
,[itmlst] ,[contxt] ,[acmode]
C Prototype
int sys$get_security (void *clsnam, void *objnam, unsigned
int *objhan, unsigned int flags, void
*itmlst, unsigned int *contxt, unsigned
int *acmode);
1 – Arguments
clsnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the object class. The clsnam argument is the address of a
descriptor pointing to a string containing the name of the object
class.
The following is a list of protected object class names:
CAPABILITY
COMMON_EVENT_CLUSTER
DEVICE
FILE
GLXSYS_GLOBAL_SECTION
GLXGRP_GLOBAL_SECTION
GROUP_GLOBAL_SECTION
ICC_ASSOCIATION
LOGICAL_NAME_TABLE
QUEUE
RESOURCE_DOMAIN
SECURITY_CLASS
SYSTEM_GLOBAL_SECTION
VOLUME
objnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Name of the protected object whose associated security profile
is going to be retrieved. The objnam argument is the address
of a descriptor pointing to a string containing the name of the
protected object.
The format of an object name is class specific. The following
table lists object names and describes their formats:
Object Class Object Name Format
CAPABILITY A character string. Currently, the only
capability object is VECTOR.
COMMON_EVENT_ Name of the event flag cluster, as defined
CLUSTER in the Associate Common Event Flag Cluster
($ASCEFC) system service.
DEVICE Standard device specification, described in
the OpenVMS User's Manual.
FILE Standard file specification, described in the
OpenVMS User's Manual.
GROUP_GLOBAL_ Section name, as defined in the Create and
SECTION Map Section ($CRMPSC) system service.
ICC_ASSOCIATION ICC security object name node::association_
name. The special node name, ICC$::, refers
to entries in the clusterwide registry. For
registry entries, the Access Access Type does
not apply.
LOGICAL_NAME_TABLE Table name, as defined in the Create Logical
Name Table ($CRELNT) system service.
QUEUE Standard queue name, as described in the Send
to Job Controller ($SNDJBC) system service.
RESOURCE_DOMAIN An identifier or octal string enclosed in
brackets.
SECURITY_CLASS Any class name shown in column 1, or a
class name followed by a period (.) and
the template name. Use the DCL command SHOW
SECURITY to display possible template names.
SYSTEM_GLOBAL_ Section name, as defined in the Create and
SECTION Map Section ($CRMPSC) system service.
VOLUME Volume name or name of the device on which
the volume is mounted.
objhan
OpenVMS usage:object_handle
type: longword (unsigned)
access: read only
mechanism: by reference
Data structure identifying the object whose associated
characteristics are going to be retrieved. The objhan argument
is an address of a longword containing the object handle. You can
use the objhan argument as an alternative to the objnam argument;
for example, channel number clearly specifies the file open on
the channel and can serve as an object handle.
The following table shows the format of the object classes:
Object Class Object Handle Format
COMMON_EVENT_CLUSTER Event flag number
DEVICE Channel number
FILE Channel number
RESOURCE_DOMAIN Resource domain identifier
VOLUME Channel number
flags
OpenVMS usage:flags
type: mask_longword
access: read only
mechanism: by value
Mask specifying processing options. The flags argument is a
longword bit vector wherein a bit, when set, specifies the
processing option. The flags argument requires the contxt
argument.
The following table describes each flag:
Symbolic Name Description
OSS$M_RELCTX Release the context structure at the completion
of this request.
OSS$M_WLOCK Maintain a write lock on the security profile
at the completion of this request. $GET_SECURITY
ignores the flag if the context has already been
established.
These symbolic names are defined in the $OSSDEF macro. You
construct the flags argument by specifying the symbolic names
of each flag.
itmlst
OpenVMS usage:item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the process or
processes is to be returned. The itmlst argument is the address
of a list of item descriptors, each of which describes an item
of information. The list of item descriptors is terminated by a
longword of 0.
With the item list, the user retrieves the protected object's
characteristics. The user defines which security characteristics
to retrieve. If this argument is not present, only the flags
argument is processed. Without the itmlst argument, you can only
manipulate the security profile lock or release contxt resources.
Refer to the VSI OpenVMS System Services Reference Manual to view
the item code diagram and descriptor fields table.
contxt
OpenVMS usage:context
type: longword (unsigned)
access: modify
mechanism: by reference
Value used to maintain the processing context when dealing with
a single protected object across multiple $GET_SECURITY/$SET_
SECURITY calls. Whenever the context value is nonzero, the class
name, object name, or object handle arguments are disregarded.
An input value of 0 indicates that a new context should be
established.
Because an active context block consumes process memory, be sure
to release the context block by setting the RELCTX flag when the
profile processing is complete. $GET_SECURITY sets the context
argument to 0 once the context is released.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by reference
Access mode to be used in the object protection check. The acmode
argument is the address of a longword containing the access mode.
The acmode argument defaults to kernel mode; however, the system
compares acmode with the caller's access mode and uses the least
privileged mode. The access modes are defined in the system macro
$PSLDEF library. VSI recommends that this argument be omitted
(passed as zero).