HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$GET_UNWIND_ENTRY_INFO (I64 Only)

Gets fixed-up unwind entry information.

Format

SYS$GET_UNWIND_ENTRY_INFO pc, get_ue_block, name


C Prototype

int SYS$GET_UNWIND_ENTRY_INFO (unsigned __int64 pc, void *get_ue_block, void *name);


Arguments

pc


OpenVMS usage: PC value
type: quadword (unsigned)
access: read only
mechanism: by value

Input quadword, target PC (that is, the PC for a code region the user wants unwind information for).

get_ue_block


OpenVMS usage: unwind_entry_data_block
type: quadword (unsigned)
access: write
mechanism: by reference

Address of a 4-quadword block to be filled in. That is, input the address of a 4 quadword block and, on successful returned status, that block will be updated with the following information:
  • code_start_va - Output quadword, the process virtual starting c unwind region containing the input IP.
  • code_end_va - Output quadward, the process virtual ending code address of the unwind region containing the input IP.
  • uib_start_va - Output quadword, the process virtual address of the UIB for the unwind region containing the input IP.
  • gp_value - Output quadword, the GP value for this code region.

name


OpenVMS usage: pseudo-image-name
type: character-code-text-string
access: modify
mechanism: by descriptor-fixed-length string descriptor

Optional, that is, may be zero. If the name parameter is specified and if a name was registered for the unwind region, then the descriptor pointer and length are updated to point to that stored name. Note that if the name parameter is specified but no name exists in the unwind tables, then the name descriptor is updated to zero length.

Description

Get fixed up unwind entry information relevant to the input instruction pointer (IP).

Required Access or Privileges

None

Required Quota

None

Related Services

SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE. Also refer to LIB$GET_UIB_INFO in HP OpenVMS Calling Standard.


Condition Values Returned

SS$_NORMAL Routine completed successfully.
SS$_IVADDR Invalid PC.
SS$_NODATA No unwind information found.

$GET_USER_CAPABILITY (Alpha and I64)

On Alpha and I64 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 HP 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.

$GOTO_UNWIND (Alpha Only)

On Alpha systems, unwinds the call stack. On I64 systems, do not use this service; use $GOTO_UNWIND_64 instead.

Format

SYS$GOTO_UNWIND target_invo ,target_pc ,[new_r0] ,[new_r1]


C Prototype

int sys$goto_unwind (void *target_invo, void *(*(target_pc)), unsigned __int64 *new_r0, unsigned __int64 *new_r1);


Arguments

target_invo


OpenVMS usage: invo_handle
type: longword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains a handle for the target invocation.

If you do not specify the target_invo argument, or if the handle value is 0, an exit unwind is initiated.

target_pc


OpenVMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains the address at which execution should continue in the target invocation.

If the target_pc argument is omitted or the value is 0, a system-defined target PC is assumed and execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

new_r0


OpenVMS usage: quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains the value to place in the saved R0 location of the mechanism argument vector. The contents of this location are then loaded into the processor R0 register at the time that execution continues in the target invocation.

If the new_r0 argument is omitted, the contents of the processor R0 register at the time of the call to $GOTO_UNWIND are used.

new_r1


OpenVMS usage: quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference

Address of a location that contains the value to place in the saved R1 location of the mechanism argument vector. The contents of the location are then loaded into the processor R1 register at the time that execution continues in the target invocation.

If the new_r1 argument is omitted, the contents of the processor R1 register at the time of the call to $GOTO_UNWIND are used.


Description

The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$UNWIND


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The specified target_invo, target_pc, new_r0, or new_r1 argument is not accessible.

$GOTO_UNWIND_64 (Alpha and I64)

On Alpha and I64 systems, unwinds the call stack.

Format

SYS$GOTO_UNWIND target_invo ,target_pc ,[NewRetVal] , [NewRetVal2]


C Prototype

int sys$goto_unwind_64 (void *target_invo_64, void *(*(target_pc_64)), unsigned_int64 *new_retval, unsigned_int64 *newretval2);


Arguments

target_invo


OpenVMS usage: invo_handle
type: quadword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains a handle for the target invocation.

If you do not specify the target_invo argument, or if the handle value is 0, the effect of the call is undefined.

target_pc


OpenVMS usage: address
type: quadword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains the address at which execution should continue in the target invocation.

If the target_pc argument is omitted or the value is 0, execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

If the target_invo argument is omitted or the value is 0, the target_pc argument is ignored. In this case, a system-defined target PC is assumed.

NewRetVal


OpenVMS usage: quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains the value to place in the saved RetVal location of the mechanism argument vector. The contents of this location are then loaded into RetVal at the time that execution continues in the target invocation.

If the NewRetVal argument is omitted, the contents of RetVal at the time of the call to $GOTO_UNWIND_64 are used.

This argument is called New_R0 in SYS$GOTO_UNWIND for compatibility with Alpha.

NewRet2


OpenVMS usage: quadword_unsigned
type: quadword (unsigned)
access: read only
mechanism: by reference

The address of a location that contains the value to place in the saved RetVal2 location of the mechanism argument vector. The contents of the location are then loaded into RetVal2 at the time that execution continues in the target invocation.

If the NewRet2 argument is omitted, the contents of RetVal2 at the time of the call to $GOTO_UNWIND_64 are used.

This argument is called New_R1 in SYS$GOTO_UNWIND for compatibility with Alpha.


Description

The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$UNWIND


Condition Values Returned

SS$_ACCVIO An invalid address was given.

$GRANTID

Adds the specified identifier record to the rights list of the process or the system.

Format

SYS$GRANTID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]


C Prototype

int sys$grantid (unsigned int *pidadr, void *prcnam, struct _generic_64 *id, void *name, unsigned int *prvatr, unsigned int segment);


Arguments

pidadr


OpenVMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference

Process identification (PID) number of the process affected when $GRANTID completes execution. The pidadr argument is the address of a longword containing the PID of the process to be affected. You use --1 to indicate the system rights list. When pidadr is passed, it is also returned; therefore, you must pass it as a variable rather than a constant. If you specify neither pidadr nor prcnam, your own process is used.

prcnam


OpenVMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Process name on which $GRANTID operates. The prcnam argument is the address of a character string descriptor containing the process name. The maximum length of the name is 15 characters. Because the UIC group number is interpreted as part of the process name, you must use pidadr to specify the rights list of a process in a different group. If you specify neither pidadr nor prcnam, your own process is used.

id


OpenVMS usage: rights_holder
type: quadword (unsigned)
access: modify
mechanism: by reference

Identifier and attributes to be granted when $GRANTID completes execution. The id argument is the address of a quadword containing the binary identifier code to be granted in the first longword and the attributes in the second longword.

Use the id argument to modify the attributes of the identifier.

Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position are defined in the macro library ($KGBDEF):

Bit Position Meaning When Set
KGB$V_DYNAMIC Allows holders of the identifier to remove it from or add it to the process rights database using the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

You must specify either id or name. Because the id argument is returned as well as passed if you specify name, you must pass it as a variable rather than a constant in this case.

name


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed-length string descriptor

Name of the identifier granted when $GRANTID completes execution. The name argument is the address of a descriptor pointing to the name of the identifier. The identifier is granted as it is created. You must specify either id or name.

prvatr


OpenVMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference

Previous attributes of the identifier. The prvatr argument is the address of a longword used to store the attributes of the identifier if it was previously present in the rights list. If you added rather than modified the identifier, prvatr is ignored.

Description

The Grant Identifier to Process service adds the specified identifier to the rights list of the process or the system. If the identifier is already in the rights list, its attributes are modified to those specified. This service is meant to be used by a privileged subsystem to alter the access rights profile of a user, based on installation policy. It is not meant to be used by the general system user.

The result of passing the pidadr or the prcnam argument, or both, to SYS$GRANTID is summarized in the following table:

prcnam pidadr Result
Omitted Omitted Current process ID is used; process ID is not returned.
Omitted 0 Current process ID is used; process ID is returned.
Omitted Specified Specified process ID is used.
Specified Omitted Specified process name is used; process ID is not returned.
Specified 0 Specified process name is used; process ID is returned.
Specified Specified Specified process ID is used and process name is ignored.

The result of passing the name or the id argument, or both, to SYS$GRANTID is summarized in the following table:

name id Result
Omitted Omitted Illegal. The INSFARG condition value is returned.
Omitted Specified Specified identifier value is used.
Specified Omitted Specified identifier name is used; identifier value is not returned.
Specified 0 Specified identifier name is used; identifier value is returned.
Specified Specified Specified identifier value is used and identifier name is ignored.

Note that a value of 0 in either of the preceding tables indicates that the contents of the address specified by the argument is the value 0. The word omitted indicates that the argument was not supplied.

Required Access or Privileges

You need CMKRNL privilege to invoke this service. In addition, you need GROUP privilege to modify the rights list of a process in the same group as the calling process (unless the process has the same UIC as the calling process). You need WORLD privilege to modify the rights list of a process outside the caller's group. You need SYSNAM privilege to modify the system rights list.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY


Condition Values Returned

SS$_WASCLR The service completed successfully; the rights list did not contain the specified identifier.
SS$_WASSET The service completed successfully; the rights list already held the specified identifier.
SS$_ACCVIO The pidadr argument cannot be read or written; prcnam cannot be read; id cannot be read or written; the name cannot be read; or prvatr cannot be written.
SS$_INSFARG You did not specify either the id or the name argument.
SS$_INSFMEM The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT The specified identifier name is invalid; the identifier name is longer than 31 characters, contains an illegal character, or does not contain at least one nonnumeric character.
SS$_IVLOGNAM You specified an invalid process name.
SS$_NONEXPR You specified a nonexistent process.
SS$_NOPRIV The caller does not have CMKRNL privilege or is not running in executive or kernel mode, or the caller lacks GROUP, WORLD, or SYSNAM privilege as required.
SS$_NOSUCHID The specified identifier name does not exist in the rights database. Note that the binary identifier, if given, is not validated against the rights database.
SS$_NOSYSNAM The operation requires SYSNAM privilege.
SS$_RIGHTSFULL The rights list of the process or system is full.
RMS$_PRV The user does not have read access to the rights database.


Previous Next Contents Index