 |
OpenVMS RTL Library (LIB$) Manual
LIB$FREE_TIMER
The Free Timer Storage routine frees the storage allocated by
LIB$INIT_TIMER.
Format
LIB$FREE_TIMER handle-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
handle-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to a block of storage containing the value returned by a
previous call to LIB$INIT_TIMER; this is the storage that
LIB$FREE_TIMER deallocates. The handle-address
argument is the address of an unsigned longword containing that value.
Description
LIB$FREE_TIMER frees a block of storage previously allocated by
LIB$INIT_TIMER. LIB$FREE_TIMER assumes that
handle-address was returned by a previous call to
LIB$INIT_TIMER. If the block referred to by
handle-address was not allocated by LIB$INIT_TIMER,
LIB$FREE_TIMER returns an error. If the routine completes successfully,
LIB$FREE_TIMER sets handle-address to zero.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Bad block address; LIB$FREE_TIMER could not deallocate the block to
which
handle-address points.
|
|
LIB$_INVARG
|
Invalid argument;
handle-address was not supplied or did not point to a
timer block.
|
LIB$FREE_VM
The Free Virtual Memory from Program Region routine deallocates an
entire block of contiguous bytes that was allocated by a previous call
to LIB$GET_VM. The arguments passed are the same as for LIB$GET_VM.
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$FREE_VM number-of-bytes ,base-address [,zone-id]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-bytes
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of contiguous bytes to be deallocated by LIB$FREE_VM. The
number-of-bytes argument is the address of a signed
longword integer that contains this number. The value of
number-of-bytes must be greater than zero.
Byte counts are rounded in the same manner as in LIB$GET_VM.
Note
You may omit the number-of-bytes argument if you are
using boundary tags (LIB$M_VM_BOUNDARY_TAGS).
|
base-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of the first byte to be deallocated by LIB$FREE_VM. The
base-address argument contains the address of an
unsigned longword that is this address. The value of
base-address must be the address of a block of memory
that was allocated by a previous call to LIB$GET_VM.
zone-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The address of a longword that contains a zone identifier created by a
previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.
You must specify the same zone-id value as when you
called LIB$GET_VM to allocate the block. An error status will be
returned if you specify an incorrect zone-id. The
zone-id argument is optional. If
zone-id is omitted or if the longword contains the
value 0, the 32-bit default zone is used.
Description
LIB$FREE_VM returns the block of memory to a free list associated with
the zone, so the block is available on a subsequent call to LIB$GET_VM
for the zone.
The base-address argument must contain the address of
the first byte of memory that was allocated by a previous call to
LIB$GET_VM. LIB$FREE_VM rounds up the value of
number-of-bytes to a multiple of the block size for
the zone.
Note
You cannot free part of a block that was allocated by a call to
LIB$GET_VM. The whole block must be freed by a single call to
LIB$FREE_VM.
Neither can you combine contiguous blocks of memory that were allocated
by several calls to LIB$GET_VM into one larger block that is freed by a
single call to LIB$FREE_VM.
|
If you specified deallocation filling when you created the zone,
LIB$FREE_VM will fill each byte freed. Note that part of a free block
is used to store control information, so some bytes will not contain
the fill value.
LIB$FREE_VM is fully reentrant, so it can be called by routines
executing at AST-level or in an Ada multitasking environment.
If the zone you are freeing was created using the
LIB$CREATE_USER_VM_ZONE routine, then you must have an appropriate
action routine for the free operation. That is, in your call to
LIB$CREATE_USER_VM_ZONE, you must have specified a user deallocation
procedure.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
The
base-address argument contained a bad block address.
Either an address was outside of the area allocated by LIB$GET_VM, the
contents of
base-address were not properly aligned, part of the
space being deallocated was previously deallocated, or a zone was found
to be corrupt.
|
|
LIB$_BADBLOSIZ
|
The
number-of-bytes argument is less than or equal to 0,
or the
number-of-bytes argument is incorrect for a zone
containing fixed size blocks.
|
|
LIB$_BADTAGVAL
|
For a zone that uses boundary tags, the tag field was corrupted.
|
LIB$FREE_VM_64 (Alpha Only)
The Free Virtual Memory from Program Region routine deallocates an
entire block of contiguous bytes that was allocated by a previous call
to LIB$GET_VM_64. The arguments passed are the same as for
LIB$GET_VM_64.
Format
LIB$FREE_VM_64 number-of-bytes ,base-address [,zone-id]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-bytes
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of contiguous bytes to be deallocated by LIB$FREE_VM_64. The
number-of-bytes argument is the address of a signed
quadword integer that contains this number. The value of
number-of-bytes must be greater than zero.
Byte counts are rounded in the same manner as in LIB$GET_VM_64.
Note
You may omit the number-of-bytes argument if you are
using boundary tags (LIB$M_VM_BOUNDARY_TAGS).
|
base-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of the first byte to be deallocated by LIB$FREE_VM_64. The
base-address argument contains the address of an
unsigned quadword that is this address. The value of
base-address must be the address of a block of memory
that was allocated by a previous call to LIB$GET_VM_64.
zone-id
| OpenVMS usage: |
identifier |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
The address of a quadword that contains a zone identifier created by a
previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.
You must specify the same zone-id value as when you
called LIB$GET_VM_64 to allocate the block. An error status will be
returned if you specify an incorrect zone-id. The
zone-id argument is optional. If
zone-id is omitted or if the quadword contains the
value 0, the 64-bit default zone is used.
Description
LIB$FREE_VM_64 returns the block of memory to a free list associated
with the zone, so the block is available on a subsequent call to
LIB$GET_VM_64 for the zone.
The base-address argument must contain the address of
the first byte of memory that was allocated by a previous call to
LIB$GET_VM_64. LIB$FREE_VM_64 rounds up the value of
number-of-bytes to a multiple of the block size for
the zone.
Note
You cannot free part of a block that was allocated by a call to
LIB$GET_VM_64. The whole block must be freed by a single call to
LIB$FREE_VM_64.
Neither can you combine contiguous blocks of memory that were allocated
by several calls to LIB$GET_VM_64 into one larger block that is freed
by a single call to LIB$FREE_VM_64.
|
If you specified deallocation filling when you created the zone,
LIB$FREE_VM_64 will fill each byte freed. Note that part of a free
block is used to store control information, so some bytes will not
contain the fill value.
LIB$FREE_VM_64 is fully reentrant, so it can be called by routines
executing at AST-level or in an Ada multitasking environment.
If the zone you are freeing was created using the
LIB$CREATE_USER_VM_ZONE_64 routine, then you must have an appropriate
action routine for the free operation. That is, in your call to
LIB$CREATE_USER_VM_ZONE_64, you must have specified a user deallocation
procedure.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
The
base-address argument contained a bad block address.
Either an address was outside of the area allocated by LIB$GET_VM_64,
the contents of
base-address were not properly aligned, part of the
space being deallocated was previously deallocated, or a zone was found
to be corrupt.
|
|
LIB$_BADBLOSIZ
|
The
number-of-bytes argument is less than or equal to 0,
or the
number-of-bytes argument is incorrect for a zone
containing fixed size blocks.
|
|
LIB$_BADTAGVAL
|
For a zone that uses boundary tags, the tag field was corrupted.
|
LIB$FREE_VM_PAGE
The Free Virtual Memory Page routine deallocates a block of contiguous
pages on VAX systems or pagelets on Alpha systems that were allocated
by previous calls to LIB$GET_VM_PAGE.
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$FREE_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 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 systems to be deallocated. The value of
number-of-pages must be greater than zero.
base-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Block address. The base-address argument is the
address of a longword that contains the address of the first byte of
the first VAX page or Alpha pagelet to be deallocated.
Description
LIB$FREE_VM_PAGE deallocates a block of contiguous 512-byte pages
starting at base-address. Each of the pages or
pagelets specified by number-of-pages and
base-address must have been allocated by previous
calls to LIB$GET_VM_PAGE. The pages or pagelets are returned to the
processwide pool and are available to satisfy subsequent calls to
LIB$GET_VM_PAGE.
You can free a smaller group of pages or pagelets than you allocated.
That is, if you allocated a group of contiguous pages or pagelets by a
single call to LIB$GET_VM_PAGE, you can deallocate them in several
calls to LIB$FREE_VM_PAGE. You can also combine contiguous groups of
pages or pagelets that were allocated in several calls to
LIB$GET_VM_PAGE into one large group that is freed by a single call to
LIB$FREE_VM_PAGE.
LIB$FREE_VM_PAGE is fully reentrant, so it may be called by routines
executing at AST level or in an Ada multitasking environment.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Pages on VAX systems or pagelets on Alpha systems not allocated by
LIB$GET_VM_PAGE, the value of
base-address is not a page boundary, or the pages were
previously freed.
|
|
LIB$_BADBLOSIZ
|
The
number-of-pages argument is less than or equal to zero.
|
LIB$FREE_VM_PAGE_64 (Alpha Only)
The Free Virtual Memory Page routine deallocates a block of contiguous
Alpha pagelets that was allocated by previous calls to
LIB$GET_VM_PAGE_64.
Format
LIB$FREE_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 pagelets. The address of a quadword integer that
specifies the number of contiguous Alpha pagelets to be deallocated.
The value of number-of-pages must be greater than zero.
base-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Block address. The base-address argument is the
address of a quadword that contains the address of the first byte of
the first Alpha pagelet to be deallocated.
Description
LIB$FREE_VM_PAGE_64 deallocates a block of contiguous Alpha pagelets
starting at base-address. Each of the pagelets
specified by number-of-pages and
base-address must have been allocated by previous
calls to LIB$GET_VM_PAGE_64. The pagelets are returned to the
processwide pool and are available to satisfy subsequent calls to
LIB$GET_VM_PAGE_64.
You can free a smaller group of pagelets than you allocated. That is,
if you allocated a group of contiguous pagelets by a single call to
LIB$GET_VM_PAGE_64, you can deallocate them in several calls to
LIB$FREE_VM_PAGE_64. You can also combine contiguous groups of pagelets
that were allocated in several calls to LIB$GET_VM_PAGE_64 into one
large group that is freed by a single call to LIB$FREE_VM_PAGE_64.
LIB$FREE_VM_PAGE_64 is fully reentrant, so it may be called by routines
executing at AST level or in an Ada multitasking environment.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Alpha pagelets not allocated by LIB$GET_VM_PAGE_64, the value of
base-address is not a pagelet boundary, or the
pagelets were previously freed.
|
|
LIB$_BADBLOSIZ
|
The
number-of-pages argument is less than or equal to zero.
|
LIB$GETDVI
The Get Device/Volume Information routine provides a simplified
interface to the $GETDVI system service. It returns information about
the primary and secondary device characteristics of an I/O device. The
calling process need not have a channel assigned to the device about
which it wants information.
Format
LIB$GETDVI item-code [,channel] [,device-name]
[,longword-integer-value] [,resultant-string] [,resultant-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
item-code
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Code specifying the item of information you are requesting. The
item-code argument is the address of a signed longword
containing the item code. All valid $GETDVI item codes whose names
begin with DVI$_ are accepted.
See the Description section for more information on item codes.
channel
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
OpenVMS I/O channel assigned to the device for which LIB$GETDVI returns
information. The channel argument is the address of an
unsigned word containing the channel specification. If
channel is not specified, device-name
is used instead. You must specify either channel or
device-name, but not both. If neither is specified,
the error status SS$_IVDEVNAM is returned.
device-name
| OpenVMS usage: |
device_name |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the device for which LIB$GETDVI returns information. The
device-name argument is the address of a descriptor
pointing to the device name string. If this string contains a colon,
the colon and the characters that follow it are ignored.
The device-name may be either a physical device name
or a logical name. If the first character in the string is an
underscore character (_), the name is considered a physical device
name. Otherwise, the name is considered a logical name, and logical
name translation is performed until either a physical device name is
found or the system default number of translations has been performed.
If device-name is not specified,
channel is used instead. You must specify either
channel or device-name, but not both.
If neither is specified, the error status SS$_IVDEVNAM is returned. The
device name must not be longer than 255 characters.
longword-integer-value
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Numeric value of the information requested. The
longword-integer-value argument is the address of a
signed longword containing the numeric value. If an item is listed as
only returning a string value, this argument is ignored.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String representation of the information requested. The
resultant-string argument is the address of a
descriptor pointing to this information. If
resultant-string is not specified and if the value
returned has only a string representation, the error status LIB$_INVARG
is returned.
Refer to Table lib-4 for a description of the string representation
used for each item.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of significant characters written to
resultant-string by LIB$GETDVI. The
resultant-length argument is the address of an
unsigned word containing this length.
Description
LIB$GETDVI returns two categories of information:
- Primary device characteristics
- Secondary device characteristics
LIB$GETDVI does not allow you to get more than one item of information
in a single call.
LIB$GETDVI provides the following features in addition to those
provided by the $GETDVI system service.
- Instead of a list of item descriptors, which may be difficult to
construct in high-level languages, the single item desired is specified
as an integer code which is passed by reference. Results are written to
separate arguments.
- For items which return numeric values, LIB$GETDVI can optionally
provide a formatted string interpretation of the value. For example, if
the device owner UIC is requested, LIB$GETDVI can return the UIC
formatted as [identifier].
- For string arguments, LIB$GETDVI understands all string classes
supported by the Run-Time Library.
- Calls to LIB$GETDVI are synchronous; LIB$GETDVI calls LIB$GET_EF to
allocate a local event flag number for synchronization.
See the description of the $GETDVI system service in the OpenVMS System Services Reference Manual: A--GETUAI
for more detailed information.
|
