Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Previous | 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