Document revision date: 19 July 1999

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

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

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.

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.

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.

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.

	privacy and legal statement
4527PRO_055.HTML