 |
OpenVMS System Services Reference Manual
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.
The following diagram depicts a single item descriptor:
The following table describes the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word containing an integer specifying the length (in bytes) of the
buffer in which $GET_SECURITY is to write the information. The length
of the buffer needed depends on the item code specified in the item
code field of the item descriptor. If the value of buffer length is too
small, $GET_SECURITY truncates the data.
|
|
Item code
|
A word containing a symbolic code specifying the item of information
that $GET_SECURITY is to return. The $OSSDEF macro defines these codes.
A description of each item code is given in the Item Codes section.
|
|
Buffer address
|
A longword containing the address of the buffer in which $GET_SECURITY
is to write the information.
|
|
Return length address
|
A longword containing the address of a word in which $GET_SECURITY
writes the length (in bytes) of the information it actually returns.
|
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. Compaq recommends that this argument be omitted
(passed as zero).
Item Codes The following table provides a summary of item codes that
are valid in an item descriptor in the itmlst
argument. Complete descriptions of each item code are provided after
the table.
| Item Identifier |
Description |
|
OSS$_ACCESS_NAMES
|
Returns access bitname translation table for the class.
|
|
OSS$_ACCESS_NAMES_LENGTH
|
Returns the size (in bytes) of the access bitname translation table.
|
|
OSS$_ACL_FIND_ENTRY
|
Locates an access control entry (ACE).
|
|
OSS$_ACL_FIND_NEXT
|
Positions to the next ACE.
|
|
OSS$_ACL_FIND_TYPE
|
Locates an ACE of specified type.
|
|
OSS$_ACL_GRANT_ACE
|
Locates an ACE that either grants or denies access.
|
|
OSS$_ACL_LENGTH
|
Returns the length of the access control list (ACL).
|
|
OSS$_ACL_POSITION_BOTTOM
|
Sets a marker that points to the end of the ACL.
|
|
OSS$_ACL_POSITION_TOP
|
Sets a marker that points to the beginning of the ACL.
|
|
OSS$_ACL_READ
|
Reads the entire ACL.
|
|
OSS$_ACL_READ_ENTRY
|
Reads an ACE.
|
|
OSS$_CLASS_NAME
|
Returns the full object class name.
|
|
OSS$_FIRST_TEMPLATE
|
Returns the name of the first template profile of a Security_Class
object.
|
|
OSS$_NEXT_OBJECT
|
Returns the name of the next Security_Class object.
|
|
OSS$_NEXT_TEMPLATE
|
Returns the name of the next template profile of a Security_Class
object.
|
|
OSS$_OBJECT_NAME
|
Returns the name of the object. The FILE class does not return an
object name.
|
|
OSS$_OWNER
|
Returns the UIC or general identifier of the object's owner.
|
|
OSS$_PROTECTION
|
Returns the protection code of the object.
|
OSS$_ACCESS_NAMES
Returns the access name translation table in the buffer pointed to by
the buffer address field of the item descriptor.
The access name translation table is a 32-quadword vector followed by a
variable section containing the access names. Each bit in the vector
represents a single access type. The contents of the quadword is a
string descriptor that corresponds to the ASCII bitname string.
Undefined access types have zero-length names. The return length, if
present, returns the length of the table.
OSS$_ACCESS_NAMES_LENGTH
Returns the length of the access name translation table.
OSS$_ACL_FIND_ENTRY
Locates an ACE pointed to by the buffer address. OSS$_ACL_FIND_ENTRY
sets the position within the ACL for succeeding ACL operations; for
example, for a deletion or modification of the ACE. If the buffer
address is 0, it returns SS$_ACCVIO.
OSS$_ACL_FIND_NEXT
Advances the current position to the next ACE in the ACL.
OSS$_ACL_FIND_TYPE
Returns an ACE of a particular type if there is one in the buffer
pointed to by the buffer address. OSS$_ACL_FIND_TYPE sets the position
within the ACL for succeeding ACL operations. If the buffer address is
0, it returns SS$_ACCVIO.
OSS$_ACL_GRANT_ACE
Returns the ACE in the object's ACL that grants or denies the user
access to that object. OSS$_ACL_GRANT_ACE returns the ACE found in the
buffer pointed to by the buffer address.
OSS$_ACL_LENGTH
Returns the size (in bytes) of the object's ACL. The buffer address
field points to a longword that receives the size.
OSS$_ACL_POSITION_BOTTOM
Sets the ACL position to point to the bottom of the ACL.
OSS$_ACL_POSITION_TOP
Sets the ACL position to point to the top of the ACL.
OSS$_ACL_READ
Returns the portion of the object's ACL to the buffer pointed to by the
buffer address.
OSS$_ACL_READ_ENTRY
Reads the ACE pointed to by the buffer address.
OSS$_CLASS_NAME
Returns the full object class name.
OSS$_FIRST_TEMPLATE
Returns the name of the first template profile for the object named in
the objnam argument. This item code is valid only for
security class objects. If the clsnam is not
Security_Class, SS$_INVCLSITM is returned.
OSS$_NEXT_OBJECT
Returns the name of the next object. A return length of 0 indicates the
end of the list. This item code is valid only for security class
objects. If the clsnam is not Security_Class,
SS$_INVCLSITM is returned.
OSS$_NEXT_TEMPLATE
Returns the name of the next template. This item code allows you to
step through a list of an object's templates. A return length of 0
indicates the end of the list. This item code is valid only for
security class objects. If the clsnam is not
Security_Class, SS$_INVCLSITM is returned.
OSS_OBJECT_NAME
Returns the name of the object.
OSS$_OWNER
Returns the owner of the object.
OSS$_PROTECTION
Returns the protection code of the object.
Description
The Get Security service returns information about security
characteristics of a selected object. Security characteristics include
such information as the protection code, the owner, and the access
control list (ACL). The security management services, $GET_SECURITY and
$SET_SECURITY, maintain a single master copy of a profile for every
security object in an OpenVMS Cluster environment. They also ensure
that only one process at a time can modify an object's security profile.
There are different ways of identifying which protected object
$GET_SECURITY should process:
- Whenever the contxt argument has a nonzero value,
$GET_SECURITY uses the context to select the object and ignores the
class name, object name, and object handle.
- With some types of objects, such as a file or a device, it is
possible to select an object on the basis of its
objhan and clsnam values.
- If neither a nonzero contxt argument nor an
objhan argument is provided, $GET_SECURITY uses an
object's class name (clsnam) and object name
(objnam) to select the object.
When you call $GET_SECURITY, the service selects the specified
protected object and fetches a local copy of the object's security
profile.
The context for a security management operation can be established
through either $GET_SECURITY or $SET_SECURITY. Whenever the context is
set by one service, the other service can use it, provided the
necessary locks are being held. If you intend to modify the profile,
you must set the write lock flag (OSS$M_WLOCK) when you establish the
context.
There are many situations in which the contxt argument
is essential. By establishing a context for an ACL operation, for
example, a caller can retain an ACL position across calls to
$GET_SECURITY so that a set of ACEs can be read and modified
sequentially. A security context is released by a call to $SET_SECURITY
or $GET_SECURITY that sets the OSS$M_RELCTX flag. Once the context is
released, the user-supplied context longword is set to 0.
Required Access or Privileges
Read or control access to the object is required.
Required Quota
None
Related Services
$SET_SECURITY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The parameter cannot be read and the buffer cannot be written.
|
|
SS$_BADPARAM
|
You specified an invalid object, attribute code, or item size.
|
|
SS$_INSFARG
|
The
clsnam and
objnam arguments are not specified, the
clsnam and
objhan arguments are not specified, or the
contxt argument is not specified.
|
|
SS$_INVCLSITM
|
The item code that you specified is not supported for the class.
|
|
SS$_NOCLASS
|
The named security class does not exist.
|
|
SS$_OBJLOCKED
|
The selected object is currently write locked.
|
$GET_SYS_ALIGN_FAULT_DATA (Alpha Only)
On Alpha systems, obtains data from the system alignment fault buffer
if buffered system alignment fault data reporting has been enabled.
This service accepts 64-bit addresses.
Format
SYS$GET_SYS_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size
C Prototype
int sys$get_sys_align_fault_data (void *buffer, int buffer_size, int
*return_size);
Arguments
buffer
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read/write |
| mechanism: |
by 32- or 64-bit reference |
The user buffer in which the alignment fault data is to be stored. The
buffer argument is the 32- or 64-bit virtual address
of this buffer.
buffer_size
| OpenVMS usage: |
byte count |
| type: |
longword (signed) |
| access: |
read |
| mechanism: |
by value |
The size, in bytes, of the buffer specified by the
buffer argument.
return_size
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write |
| mechanism: |
by 32- or 64-bit reference |
The amount of data, in bytes, stored in the buffer. The
return_size argument is the 32- or 64-bit virtual
address of a naturally aligned longword into which the service returns
the amount of data, in bytes, stored in the buffer. The
return_size argument is set to 0 if there is no data
in the buffer.
Description
The Get System Alignment Fault Data service obtains data from the
system alignment fault buffer if buffered system alignment fault data
reporting has been enabled.
When buffered system alignment fault data reporting is enabled, the
operating system writes each alignment fault into a system-allocated
buffer. The user must poll this buffer periodically to read the data.
The user must call the $INIT_SYS_ALIGN_FAULT_REPORT service to enable
buffered system alignment fault data reporting. For more information,
see the $INIT_SYS_ALIGN_FAULT_REPORT service.
Required Access or Privileges
CMKRNL privilege is required.
Required Quota
None
Related Services
$GET_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT,
$PERM_DIS_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.
|
|
SS$_ACCVIO
|
The buffer named in the
buffer argument is not accessible.
|
|
SS$_AFR_NOT_ENABLED
|
Alignment fault reporting has not been enabled.
|
|
SS$_BADPARAM
|
The buffer size is smaller than the minimum defined by the
AFR$K_VMS_LENGTH or the AFR$K_EXTENDED_LENGTH symbol.
|
$GET_USER_CAPABILITY (Alpha Only)
On Alpha systems, reserves a user capability, indicating to other
processes that the resource is in use.
This service accepts 64-bit addresses.
Format
SYS$GET_USER_CAPABILITY cap_num [,select_num] [,select_mask]
[,prev_mask] [,flags]
C Prototype
int sys$get_user_capability (*cap_num, int *select_num, struct
_generic_64 *select_mask, struct _generic_64 *prev_mask, struct
_generic_64 *flags);
Arguments
cap_num
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Capability number to be reserved by the calling kernel thread. This
number can range from 1 to 16 for an explicit request, or the symbolic
constant CAP$K_GET_FREE_CAP can be specified to get the next available
user capability. The cap_num argument is the 32- or
64-bit address of the longword containing the user capability number or
symbolic constant.
select_num
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The number of the user capability selected by the service call. The
select_num argument is the 32- or 64-bit address of a
longword into which the system writes the user capability number. For
an explicit numeric request, the value returned in this longword will
match that specified in cap_num; otherwise, this cell
contains the next available user capability.
select_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
A quadword bit mask with a single bit position set, reflecting the user
capability selected by the service. The select_mask
argument is the 32- or 64-bit address of a quadword into which the
system writes the selected user capability bit mask. This bit mask is
the most efficient method for indicating the reserved user capability
with the $CPU_CAPABILITIES and $PROCESS_CAPABILITIES services.
prev_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The previous user capability reservation mask before execution of this
service call. The prev_mask argument is the 32- or
64-bit address of a quadword into which the service writes a quadword
bit mask specifying the previously reserved user capabilities taken
from the global cell SCH$GQ_RESERVED_USER_CAPS.
flags
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Options selected for the user capability reservation. The
flags argument is a quadword bit vector wherein a bit
corresponds to an option.
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.
At this time, all bits are reserved to Compaq and must be 0.
Description
The Reserve a User Capability service provides a way for discrete
processes to communicate and synchronize their use of a user capability
in the system. This service uses the global cell
SCH$GQ_RESERVED_USER_CAPS to indicate that a particular user capability
has been reserved. $GET_USER_CAPABILITY can also return the current
reservation state of all user capabilities in the system.
Reservation of a user capability can be made for an explicit number or
for the next available number. The selected user capability is returned
to the caller through a numeric value in select_num or
by a quadword bit mask in select_mask.
This service does not directly enforce unique use of the individual
user capabilities; it simply provides a common informational and
control resource for processes using the other capability scheduling
services. Code threads that do not use this service to verify whether a
user capability is available are still at risk if differing usages
conflict.
Required Privileges
The caller must have both ALTPRI and WORLD privileges to call
$GET_USER_CAPABILITY to reserve a user capability. No privileges are
required if $GET_USER_CAPABILITY is called only to retrieve the current
user capability reservation mask.
Required Quota
None
Related Services
$FREE_USER_CAPABILITY, $CPU_CAPABILITIES, $PROCESS_CAPABILITIES
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The service cannot access the locations specified by one or more
arguments.
|
|
SS$_INSFARG
|
Fewer than the required number of arguments were specified, or no
operation was specified.
|
|
SS$_NOPRIV
|
Insufficient privilege for the attempted operation.
|
|
SS$_NOSUCH_OBJECT
|
No more user capabilities are available.
|
|
SS$_OBJECT_EXISTS
|
A specifically requested user capability has already been reserved.
|
|
SS$_TOO_MANY_ARGS
|
Too many arguments were presented to the system service.
|
|
