 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$GET_VM_PAGE
The Get Virtual Memory Page routine allocates a specified number of
contiguous pages on VAX systems or pagelets on Alpha and I64 systems of
memory in the program region and returns the virtual address of the
first allocated page on VAX or pagelet on Alpha or I64.
Note
No support for arguments passed by 64-bit address reference or for use
of 64-bit descriptors, if applicable, is planned for this routine.
|
Format
LIB$GET_VM_PAGE number-of-pages ,base-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-pages
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of pages on VAX systems or pagelets on Alpha and I64 systems.
The number-of-pages argument is the address of a
longword integer that specifies the number of contiguous pages on VAX
systems or pagelets on Alpha and I64 systems to be allocated. The value
of number-of-pages must be greater than 0.
base-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Block address. The base-address argument is the
address of a longword that is set to the address of the first byte of
the newly allocated block of pages on VAX systems or pagelets on Alpha
and I64 systems.
Description
LIB$GET_VM_PAGE allocates blocks of contiguous (512 byte) pages on VAX
systems and pagelets on Alpha and I64 systems in the program region.
LIB$GET_VM_PAGE manages a processwide pool of free pages. If there are
not enough contiguous free pages or pagelets to satisfy an allocation
request, additional pages are created by calling the system service
$EXPREG. All memory allocated by LIB$GET_VM_PAGE is pagelet aligned;
that is, the low-order nine bits of the base address are zero.
All memory allocated by LIB$GET_VM_PAGE has user-mode read/write
access, even if the call to LIB$GET_VM_PAGE is made from a more
privileged access mode.
The contents of memory allocated by LIB$GET_VM_PAGE are unpredictable.
Your program must assign values to all locations that it uses.
LIB$GET_VM_PAGE is designed for request sizes ranging from one page or
pagelet to a few hundred pages or pagelets. For very large request
sizes (over 1000 pages or pagelets in a single request), you should
call the system service $EXPREG.
LIB$GET_VM_PAGE is fully reentrant, so it can be called by routines
executing at AST level or in an Ada multitasking environment.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOSIZ
|
The value of the
number-of-pages argument is less than or equal to 0.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. The request required more dynamic memory
than was available from the operating system. No partial allocation is
made in this case.
|
LIB$GET_VM_PAGE_64 (Alpha and I64 Only)
The Get Virtual Memory Page routine allocates a specified number of
contiguous Alpha or I64 pagelets of memory in the program region and
returns the virtual address of the first allocated pagelet.
Format
LIB$GET_VM_PAGE_64 number-of-pages ,base-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-pages
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of Alpha or I64 pagelets. The number-of-pages
argument is the address of a quadword integer that specifies the number
of contiguous Alpha or I64 pagelets to be allocated. The value of
number-of-pages must be greater than 0.
base-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Block address. The base-address argument is the
address of a quadword that is set to the address of the first byte of
the newly allocated block of Alpha or I64 pagelets.
Description
LIB$GET_VM_PAGE_64 allocates blocks of contiguous Alpha or I64 pagelets
in the program region. LIB$GET_VM_PAGE_64 manages a processwide pool of
free pagelets. If there are not enough contiguous free pagelets to
satisfy an allocation request, additional pagelets are created by
calling the system service $EXPREG_64. All memory allocated by
LIB$GET_VM_PAGE_64 is aligned to physical page size.
All memory allocated by LIB$GET_VM_PAGE_64 has user-mode read/write
access, even if the call to LIB$GET_VM_PAGE_64 is made from a more
privileged access mode.
The contents of memory allocated by LIB$GET_VM_PAGE_64 are
unpredictable. Your program must assign values to all locations that it
uses.
LIB$GET_VM_PAGE_64 is fully reentrant, so it can be called by routines
executing at AST level or in an Ada multitasking environment.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOSIZ
|
The value of the argument
number-of-pages is less than or equal to 0.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory. The request required more dynamic memory
than was available from the operating system. No partial allocation is
made in this case.
|
LIB$I64_CREATE_INVO_CONTEXT (I64 Only)
The Create Invocation Context routine allocates an invocation context
block from heap storage and initializes it.
Format
LIB$I64_CREATE_INVO_CONTEXT [malloc] [,free] [,ident]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
malloc
| OpenVMS usage: |
function_value |
| type: |
procedure |
| access: |
read |
| mechanism: |
by value |
A procedure reference for a user callback routine that allocates
memory. This is an optional argument. The default is to use an
implementation of the C RTL routine malloc. If
specified, this routine is used to allocate the invocation context
block field LIBICB$PH_UO_MALLOC for use during the stack walk.
free
| OpenVMS usage: |
function_value |
| type: |
procedure |
| access: |
read |
| mechanism: |
by value |
A procedure reference for a user callback routine that deallocates
memory. This value is placed in the invocation context block field
LIBICB$PH_UO_FREE. This is an optional argument; however, it must be
specified if malloc is specified. The default is to
use an implementation of the C RTL routine free.
ident
| OpenVMS usage: |
user_value |
| type: |
quadword |
| access: |
read |
| mechanism: |
by value |
Specifies a user ident value to be placed in the
invocation context block LIBICB$IH_UO_IDENT field. In turn, this value
is passed to the malloc and free
routines. This is an optional argument; the default value is zero.
Description
LIB$I64_CREATE_INVO_CONTEXT simplifies creating and properly
initializing an invocation context block. The routine allocates an
invocation context block from heap storage and initializes it. Users of
this routine should call LIB$I64_FREE_INVO_CONTEXT when the invocation
context block is no longer required.
This routine sets the cache unwind flag LIBICB$V_UO_FLAG_CACHE_UNWIND
in the invocation context block to speed up the stack walk. Do not use
this routine in conjunction with LIB$I64_INIT_INVO_CONTEXT, as the same
initialization is performed by both routines.
Condition Values Returned
|
0
|
Indicates failure.
|
|
any non-zero value
|
Represents the address of the allocated invocation context block.
|
LIB$I64_FREE_INVO_CONTEXT (I64 Only)
The Free Invocation Context Block routine deallocates an invocation
context block that was previously allocated.
Format
LIB$I64_FREE_INVO_CONTEXT invo_context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
modify only |
| mechanism: |
by reference |
Address of an invocation context block.
Description
LIB$I64_FREE_INVO_CONTEXT deallocates an invocation context block that
was previously allocated using LIB$I64_CREATE_INVO_CONTEXT. This
routine calls LIB$I64_PREV_INVO_END as a convenience.
Condition Values Returned
None.
LIB$I64_GET_CURR_INVO_CONTEXT (I64 Only)
The Get Current Invocation Context routine gets the invocation context
of a current procedure.
Format
LIB$I64_GET_CURR_INVO_CONTEXT invo_context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
modify only |
| mechanism: |
by reference |
Address of an invocation context block into which the procedure context
of the caller will be written.
Description
LIB$I64_GET_CURR_INVO_CONTEXT gets the invocation context of a current
procedure. The invocation context block must be properly initialized as
described in the HP OpenVMS Calling Standard manual before calling this routine.
Condition Values Returned
|
0
|
Facilitates use in the implementation of the C language unwind
setjmp
or
longjmp
function. Check the LIBICB$L_ALERT_CODE field of the invocation context
block for further status indication.
|
LIB$I64_GET_CURR_INVO_HANDLE (I64 Only)
The Get Current Invocation Handle routine gets the invocation handle
for the current procedure.
Format
LIB$I64_GET_CURR_INVO_HANDLE invo_handle
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
invo_handle
| OpenVMS usage: |
invo_handle |
| type: |
quadword |
| access: |
write only |
| mechanism: |
by reference |
Address of a quadword into which the invocation handle of the caller
will be written.
Description
LIB$I64_GET_CURR_INVO_HANDLE gets the invocation handle for the current
procedure.
Condition Values Returned
|
0
|
The initial context represents the bottom of the call stack.
|
|
1
|
Indicates success.
|
|
3
|
The current operation completed without error, but a stack corruption
was detected at the next level down.
|
LIB$I64_GET_FR (I64 Only)
The Get Floating-Point Register routine copies the value of the
floating-point register.
Format
LIB$I64_GET_FR invo_context, index, fr_copy
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
read |
| mechanism: |
by reference |
Address of a valid invocation context block.
index
| OpenVMS usage: |
index |
| type: |
longword |
| access: |
read |
| mechanism: |
by value |
Floating point register index.
fr_copy
| OpenVMS usage: |
floating-point value |
| type: |
octaword |
| access: |
write |
| mechanism: |
by value |
Address of an octaword to receive the contents of the specified
floating-point register.
Description
Given an invocation context block and floating-point register
index such that 0 <= index <
128, LIB$I64_GET_FR copies the register value to
fr_copy. For example, an index value
of 4 fetches the value, which represents the contents of F4 for the
context.
LIB$I64_GET_FR returns failure status if the index represents a scratch
register whose contents have not been realized.
Condition Values Returned
|
0
|
Indicates failure.
|
|
1
|
Indicates success.
|
LIB$I64_GET_GR (I64 Only)
The Get Invocation Context Block Value routine fetches the invocation
context block IREG[4] value.
Format
LIB$I64_GET_GR invo_context, index, gr_copy
RETURNS
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
read |
| mechanism: |
by reference |
Address of a valid invocation context block.
index
| OpenVMS usage: |
index |
| type: |
longword |
| access: |
read |
| mechanism: |
by value |
Index into the IREG array of the invocation context block.
gr_copy
| OpenVMS usage: |
floating-point value |
| type: |
octaword |
| access: |
write |
| mechanism: |
by value |
Address of an octaword to receive the value from the invocation context
block.
Description
Given an invocation context block and general register
index such that 0 <= index <
128, LIB$I64_GET_GR copies the register value to
gr_copy, for example, index 4 fetches
the invocation context block IREG[4] value, which represents the
contents of R4 for the context.
If the register represented by index has its
corresponding NaT bit set, the read succeeds and the return status is
set to 3. If the register represented by index lies
beyond the allocated general registers, the read fails and
gr_copy is unchanged. That is, the highest allowed
index is 32 + ICB.CFM.SOF - 1.
LIB$I64_GET_GR fails if the index represents a scratch register whose
contents have not been realized.
Condition Values Returned
|
0
|
Indicates failure.
|
|
1
|
Indicates success, and that the NaT bit was clear.
|
|
3
|
Indicates success, and that the NaT bit was set.
|
LIB$I64_GET_INVO_CONTEXT (I64 Only)
The Get Invocation Context routine gets the invocation context of any
active procedure.
Format
LIB$I64_GET_INVO_CONTEXT invo_handle, invo_context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
invo_handle
| OpenVMS usage: |
invo_handle |
| type: |
quadword |
| access: |
modify only |
| mechanism: |
by reference |
Address of an invocation context block into which the procedure context
of the frame specified by invo_handle will be written.
invo_context
| OpenVMS usage: |
invo_context_blk |
| type: |
structure |
| access: |
write only |
| mechanism: |
by reference |
Address of an invocation context block into which the procedure context
of the frame specified by invo_handle will be written.
Description
LIB$I64_GET_INVO_CONTEXT gets the invocation context of any active
procedure.
Note
The invocation context block must be properly
initialized as described in the HP OpenVMS Calling Standard manual before calling
this routine.
|
Condition Value Returned
|
0
|
Facilitates use in the implementation of the C language unwind
setjmp
or
longjmp
function. Check the LIBICB$L_ALERT_CODE field of the invocation context
block for further status indication.
|
|
