OpenVMS RTL Library (LIB$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Library (LIB$) Manual

Contents

Index

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.

Previous Next Contents Index

privacy and legal statement

5932PRO_020.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

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

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.

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

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

OpenVMS usage:	quadword_signed
type:	quadword integer (signed)
access:	read only
mechanism:	by reference

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	device_name
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference