Updated: 11 December 1998 |
OpenVMS System Services Reference Manual
Previous | Contents | Index |
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. |
OpenVMS usage: | context |
type: | longword (unsigned) |
access: | modify |
mechanism: | by reference |
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.
OpenVMS usage: | access_mode |
type: | longword (unsigned) |
access: | read only |
mechanism: | by reference |
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
When you specify OSS$_ACCESS_NAMES, $GET_SECURITY 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
When you specify OSS$_ACCESS_NAMES_LENGTH, $GET_SECURITY returns the length of the access name translation table.OSS$_ACL_FIND_ENTRY
When you specify OSS$_ACL_FIND_ENTRY, $GET_SECURITY 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
When you specify OSS$_ACL_FIND_NEXT, $GET_SECURITY advances the current position to the next ACE in the ACL.OSS$_ACL_FIND_TYPE
When you specify OSS$_ACL_FIND_TYPE, $GET_SECURITY 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
When you specify OSS$_ACL_GRANT_ACE, $GET_SECURITY 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
When you specify OSS$_ACL_LENGTH, $GET_SECURITY 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
When you specify OSS$_ACL_POSITION_BOTTOM, $GET_SECURITY sets the ACL position to point to the bottom of the ACL.OSS$_ACL_POSITION_TOP
When you specify OSS$_ACL_POSITION_TOP, $GET_SECURITY sets the ACL position to point to the top of the ACL.OSS$_ACL_READ
When you specify OSS$_ACL_READ, $GET_SECURITY returns the portion of the object's ACL to the buffer pointed to by the buffer address.OSS$_ACL_READ_ENTRY
When you specify OSS$_ACL_READ_ENTRY, $GET_SECURITY reads the ACE pointed to by the buffer address.OSS$_CLASS_NAME
When you specify OSS$_CLASS_NAME, $GET_SECURITY returns the full object class name.OSS$_FIRST_TEMPLATE
When you specify OSS$_FIRST_TEMPLATE, $GET_SECURITY 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
When you specify OSS$_NEXT_OBJECT, $GET_SECURITY 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
When you specify OSS$_NEXT_TEMPLATE, $GET_SECURITY 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
When you specify OSS$_OBJECT_NAME, $GET_SECURITY returns the name of the object.OSS$_OWNER
When you specify OSS$_OWNER, $GET_SECURITY returns the owner of the object.OSS$_PROTECTION
When you specify OSS$_PROTECTION, $GET_SECURITY returns the protection code of the object.
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.
Read or control access to the object is required.
None
$SET_SECURITY
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.
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.
SYS$GET_SYS_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size
int sys$get_sys_align_fault_data (void *buffer, int buffer_size, int *return_size);
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.
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.
CMKRNL privilege is required.
None
$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
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.
On Alpha systems, reserves a user capability, indicating to other processes that the resource is in use.This service accepts 64-bit addresses.
SYS$GET_USER_CAPABILITY cap_num [,select_num] [,select_mask] [,prev_mask] [,flags]
int sys$get_user_capability (*cap_num, int *select_num, struct _generic_64 *select_mask, struct _generic_64 *prev_mask, struct _generic_64 *flags);
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.
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.
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.
None
$FREE_USER_CAPABILITY, $CPU_CAPABILITIES, $PROCESS_CAPABILITIES
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.
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4527PRO_055.HTML
|