 |
HP OpenVMS System Services Reference Manual
$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.
|
|
