Document revision date: 30 March 2001

## OpenVMS RTL Library (LIB$) Manual

Order Number: AA-QSBHD-TE

## April 2001

This manual documents the library routines contained in the LIB$ and CVT$ facilities of the OpenVMS Run-Time Library.

Revision/Update Information: This manual supersedes OpenVMS RTL Library (LIB$) Manual, OpenVMS AXP Version 7.2 and OpenVMS VAX Version 7.2.

Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and other countries.

Motif, OSF/1, and The Open Group are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be trademarks of their respective holders.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK5932

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents | Index

## Preface

This manual provides users of the Compaq OpenVMS operating system with detailed usage and reference information on library routines supplied in the LIB$ and CVT$ facilities of the Run-Time Library (RTL).

## Intended Audience

This manual is intended for system and application programmers who write programs that call LIB$ and CVT$ Run-Time Library routines.

## Document Structure

This manual is organized into three parts as follows:

- The overview chapter provides a brief overview of the LIB$ and CVT$ Run-Time Library facility and lists the LIB$ routines and their functions. It also provides guidelines and information on using the LIB$ facility with VAX and Alpha platforms.
- The LIB$ reference section describes each library routine contained in the LIB$ Run-Time Library facility. This information is presented using the documentation format described in OpenVMS Programming Concepts Manual. Routine descriptions appear alphabetically by routine name.
- The CVT$ reference section describes the routines contained in the CVT$ Run-Time Library facility. This information is presented using the documentation format described in OpenVMS Programming Concepts Manual.

## Related Documents

The Run-Time Library (RTL) routines are documented in a series of reference manuals.

General descriptions of OpenVMS RTL routines appear in the following manual:

- OpenVMS Programming Concepts Manual---A description of OpenVMS features and functionality available through calls to the LIB$ Run-Time Library

Specific descriptions of the other RTL facilities and their corresponding routines appear in the following manuals:

- Compaq Portable Mathematics Library
- OpenVMS VAX RTL Mathematics (MTH$) Manual
- OpenVMS RTL DECtalk (DTK$) Manual1
- OpenVMS RTL General Purpose (OTS$) Manual
- OpenVMS RTL Parallel Processing (PPL$) Manual1
- OpenVMS RTL Screen Management (SMG$) Manual
- OpenVMS RTL String Manipulation (STR$) Manual

Application programmers using any language can refer to the Guide to Creating OpenVMS Modular Procedures for writing modular and reentrant code.

High-level language programmers will find additional information on calling Run-Time Library routines in their language reference manuals. Additional information may also be found in the language user's guide provided with your OpenVMS language software.

For a complete list and description of the manuals in the OpenVMS documentation set, see the OpenVMS Version 7.3 New Features and Documentation Overview.

For additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:

    http://www.openvms.compaq.com/

Note ##### 1 This manual has been archived but is available on the OpenVMS documentation CD-ROM.

## Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet | openvmsdoc@compaq.com
Mail | Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

## How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

    http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

## Conventions

In this manual, every use of DECwindows and DECwindows Motif refers to Compaq DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:

Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x | A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]` | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
... | A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . . | A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) | In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ] | In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
| | In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ } | In command format descriptions, braces indicate required choices; you must choose at least one of the options listed. Do not type the braces on the command line.
bold text | This typeface represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text | Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
`Monospace text` | Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
- | A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

## Part 1
LIB$ Overview Section

This part contains one chapter that provides a brief overview of the LIB$ and CVT$ Run-Time Library facilities and lists the LIB$ and CVT$ routines and their functions. It also provides guidelines and information on using the LIB$ facility with VAX and Alpha platforms.

## Chapter 1
Overview of the LIB$ Facility

This section describes the OpenVMS Run-Time Library (LIB$) facility and lists the function of each routine within the LIB$ facility.

## 1.1 Run-Time Library LIB$ Routines

This manual discusses the Run-Time Library (RTL) LIB$ routines that perform general purpose (library) functions. One of the functions of the LIB$ facility is to provide a callable interface to components of OpenVMS operating systems that are difficult to use in a high-level language. LIB$ routines allow access to the following:

- System services
- The command language interpreter (CLI)
- Some VAX machine instructions or the equivalent Alpha instructions

In addition, LIB$ routines allow you to perform the following operations:

- Allocate resources that your process needs, such as virtual memory and event flags
- Convert data types for I/O
- Enable detection of hardware exceptions (VAX only)
- Establish condition handlers (VAX only)
- Generate and display timing statistics while your program is running
- Get and put strings in the process common storage area
- Obtain records from devices
- Obtain the system date and time in various formats
- Process cross-reference data
- Process Compaq DECnet-Plus for OpenVMS full names
- Search for specified files
- Set up and use binary trees
- Signal exceptions

### 1.1.1 64-Bit Addressing Support (Alpha Only)

On Alpha systems, the Run-Time Library (LIB$) routines provide 64-bit virtual addressing capabilities as follows:

- Most routines now accept 64-bit addresses for arguments passed by reference. Footnotes in the Reference Section of this manual indicate those routines that do not.
- Most routines also accept either 32-bit or 64-bit descriptors for arguments passed by descriptor. Footnotes in the Reference Section of this manual indicate those routines that do not.
- In some cases, a new routine was added to support a 64-bit addressing or data capability. These routines carry the same name as the original routine but with a _64 suffix. In general, both versions of the routine support 64-bit addressing, but the routine with the _64 suffix also supports additional 64-bit capability. The 32-bit capabilities of the original routine are unchanged.
- Specialized routines create and manipulate storage zones in the 64-bit virtual address space. The names of these routines are the same as their 32-bit counterparts but with a _64 suffix. One example is LIB$CREATE_VM_ZONE and LIB$CREATE_VM_ZONE_64. LIB$CREATE_VM_ZONE creates a storage zone in the 32-bit vitual address space, and LIB$CREATE_VM_ZONE_64 creates a storage zone in the 64-bit virtual address space. The function of the original routine is unchanged.

See the OpenVMS Programming Concepts Manual for more information about 64-bit virtual addressing capabilities.

### 1.1.2 The LIB$ Routines

Table 1-1 lists all of the LIB$ routines and their functions.

Table 1-1 LIB$ Routines
Routine Name | Function
--- | ---
LIB$ADAWI | Add adjacent word with interlock.
LIB$ADDX | Add two multiple-precision binary numbers.
LIB$ADD_TIMES | Add two quadwords times.
LIB$ANALYZE_SDESC | Analyze a string descriptor.
LIB$ANALYZE_SDESC_64 | Analyze a string descriptor. 1
LIB$ASN_WTH_MBX | Assign a channel to a mailbox.
LIB$AST_IN_PROG | Check for active AST.
LIB$ATTACH | Attach a terminal to a process.
LIB$BBCCI | Test and clear a bit with interlock.
LIB$BBSSI | Test and set a bit with interlock.
LIB$BUILD_NODESPEC | Build a node-name specification.
LIB$CALLG | Call a procedure with a general argument list.
LIB$CALLG_64 | Call a procedure with a general argument list. 1
LIB$CHAR | Transform a byte to the first character of a string.
LIB$COMPARE_NODENAME | Compare two node names.
LIB$COMPRESS_NODENAME | Compress a node name to its short form equivalent.
LIB$CONVERT_DATE_STRING | Convert a date string to a quadword.
LIB$CRC | Calculate a cyclic redundancy check (CRC).
LIB$CRC_TABLE | Construct a cyclic redundancy check (CRC) table.
LIB$CREATE_DIR | Create a directory.
LIB$CREATE_USER_VM_ZONE | Create a user-defined storage zone.
LIB$CREATE_USER_VM_ZONE_64 | Create a user-defined storage zone. 1
LIB$CREATE_VM_ZONE | Create a new storage zone.
LIB$CREATE_VM_ZONE_64 | Create a new storage zone. 1
LIB$CRF_INS_KEY | Insert a key in the cross-reference table.
LIB$CRF_INS_REF | Insert a reference to a key in the cross-reference table.
LIB$CRF_OUTPUT | Output some cross-reference table information.
LIB$CURRENCY | Get the system currency symbol.
LIB$CVTF_FROM_INTERNAL_TIME | Convert internal time to external time (F-floating value).
LIB$CVTF_TO_INTERNAL_TIME | Convert external time to internal time (F-floating value).
LIB$CVT_DX_DX | Convert the specified data type.
LIB$CVT_FROM_INTERNAL_TIME | Convert internal time to external time.
LIB$CVT_TO_INTERNAL_TIME | Convert external time to internal time.
LIB$CVT_VECTIM | Convert 7-word vector to internal time.
LIB$CVT_ xTB | Convert numeric text to binary.
LIB$CVT_ xTB_64 | Convert numeric text to binary. 1
LIB$DATE_TIME | Return the date and time as a string.
LIB$DAY | Return the day number as a longword integer.
LIB$DAY_OF_WEEK | Return the numeric day of the week.
LIB$DECODE_FAULT | Decode instruction stream during a fault. 2
LIB$DEC_OVER | Enable or disable decimal overflow detection. 2
LIB$DELETE_FILE | Delete one or more files.
LIB$DELETE_LOGICAL | Delete a logical name.
LIB$DELETE_SYMBOL | Delete a CLI symbol.
LIB$DELETE_VM_ZONE | Delete a virtual memory zone.
LIB$DELETE_VM_ZONE_64 | Delete a virtual memory zone. 1
LIB$DIGIT_SEP | Get the digit separator symbol.
LIB$DISABLE_CTRL | Disable CLI interception of control characters.
LIB$DO_COMMAND | Execute the specified command.
LIB$EDIV | Perform an extended-precision divide.
LIB$EMODD | Perform extended multiply and integerize for D-floating values.
LIB$EMODF | Perform extended multiply and integerize for F-floating values.
LIB$EMODG | Perform extended multiply and integerize for G-floating values.
LIB$EMODH | Perform extended multiply and integerize for H-floating values. 2
LIB$EMUL | Perform an extended-precision multiply.
LIB$ENABLE_CTRL | Enable CLI interception of control characters.
LIB$ESTABLISH | Establish a condition handler. 2 3
LIB$EXPAND_NODENAME | Expand a node name to its full name equivalent.
LIB$EXTV | Extract a field and sign-extend.
LIB$EXTZV | Extract a zero-extended field.
LIB$FF x | Find the first clear or set bit.
LIB$FID_TO_NAME | Convert a device and file ID to a file specification.
LIB$FILE_SCAN | Perform a file scan.
LIB$FILE_SCAN_END | End a file scan.
LIB$FIND_FILE | Find a file.
LIB$FIND_FILE_END | End of find file.
LIB$FIND_IMAGE_SYMBOL | Merge activate an image symbol.
LIB$FIND_VM_ZONE | Find the next valid zone.
LIB$FIND_VM_ZONE_64 | Find the next valid zone. 1
LIB$FIT_NODENAME | Fit a node name into an output field.
LIB$FIXUP_FLT | Fix floating reserved operand. 2
LIB$FLT_UNDER | Detect a floating-point underflow. 2
LIB$FORMAT_DATE_TIME | Format a date and/or time.
LIB$FORMAT_SOGW_PROT | Format protection mask. 4
LIB$FREE_DATE_TIME_CONTEXT | Free the context used to format a date.
LIB$FREE_EF | Free an event flag.
LIB$FREE_LUN | Free a logical unit number.
LIB$FREE_TIMER | Free timer storage.
LIB$FREE_VM | Free virtual memory from the program region.
LIB$FREE_VM_64 | Free virtual memory from the program region. 1
LIB$FREE_VM_PAGE | Free a virtual memory page.
LIB$FREE_VM_PAGE_64 | Free a virtual memory page. 1
LIB$GETDVI | Get device/volume information.
LIB$GETJPI | Get job/process information.
LIB$GETQUI | Get queue information.
LIB$GETSYI | Get systemwide information.
LIB$GET_ACCNAM | Get access name table for a security object identified by name. 4
LIB$GET_ACCNAM_BY_CONTEXT | Get access name table for a security object identified by $GET_SECURITY or $SET_SECURITY context. 4
LIB$GET_COMMAND | Get line from SYS$COMMAND.
LIB$GET_COMMON | Get string from common area.
LIB$GET_CURR_INVO_CONTEXT | Get current invocation context. 1
LIB$GET_DATE_FORMAT | Return the user's date input format.
LIB$GET_EF | Get an event flag.
LIB$GET_FOREIGN | Get foreign command line.
LIB$GET_FULLNAME_OFFSET | Get the offset to the starting position of the most significant part of a full name.
LIB$GET_HOSTNAME | Get host node name.
LIB$GET_INPUT | Get line from SYS$INPUT.
LIB$GET_INVO_CONTEXT | Get invocation context. 1
LIB$GET_INVO_HANDLE | Get invocation handle. 1
LIB$GET_LUN | Get logical unit number.
LIB$GET_MAXIMUM_DATE_LENGTH | Get the maximum possible date/time string length.
LIB$GET_PREV_INVO_CONTEXT | Get previous invocation context. 1
LIB$GET_PREV_INVO_HANDLE | Get previous invocation handle. 1
LIB$GET_SYMBOL | Get the value of a CLI symbol.
LIB$GET_USERS_LANGUAGE | Return the user's language choice.
LIB$GET_VM | Allocate virtual memory.
LIB$GET_VM_64 | Allocate virtual memory. 1
LIB$GET_VM_PAGE | Get a virtual memory page.
LIB$GET_VM_PAGE_64 | Get a virtual memory page. 1
LIB$ICHAR | Convert the first character of a string to an integer.
LIB$INDEX | Index to relative position of substring.
LIB$INIT_DATE_TIME_CONTEXT | Initialize the context used in formatting date/time strings.
LIB$INIT_TIMER | Initialize times and counts.
LIB$INSERT_TREE | Insert entry in a balanced binary tree.
LIB$INSERT_TREE_64 | Insert entry in a balanced binary tree. 1
LIB$INSQHI | Insert entry at the head of a queue.
LIB$INSQHIQ | Insert entry at the head of a queue. 1
LIB$INSQTI | Insert entry at the tail of a queue.
LIB$INSQTIQ | Insert entry at the tail of a queue. 1
LIB$INSV | Insert a variable bit field.
LIB$INT_OVER | Detect integer overflow. 2
LIB$LEN | Return the length of a string as a longword.
LIB$LOCC | Locate a character.
LIB$LOOKUP_KEY | Look up keyword in table.
LIB$LOOKUP_TREE | Look up an entry in a balanced binary tree.
LIB$LOOKUP_TREE_64 | Look up an entry in a balanced binary tree. 1
LIB$LP_LINES | Specify the number of lines on each printer page.
LIB$MATCHC | Match characters, return relative position.
LIB$MATCH_COND | Match condition values.
LIB$MOVC3 | Move characters.
LIB$MOVC5 | Move characters with fill.
LIB$MOVTC | Move translated characters.
LIB$MOVTUC | Move translated until character.
LIB$MULTF_DELTA_TIME | Multiply delta time by F-floating scalar.
LIB$MULT_DELTA_TIME | Multiply delta time by scalar.
LIB$PARSE_ACCESS_CODE | Parse access-encoded name string. 4
LIB$PARSE_SOGW_PROT | Parse protection string. 4
LIB$PAUSE | Pause program execution.
LIB$POLYD | Evaluate polynomials for D-floating values.
LIB$POLYF | Evaluate polynomials for F-floating values.
LIB$POLYG | Evaluate polynomials for G-floating values.
LIB$POLYH | Evaluate polynomials for H-floating values. 2
LIB$PUT_COMMON | Put string into common area.
LIB$PUT_INVO_REGISTERS | Put invocation registers. 1
LIB$PUT_OUTPUT | Put line to SYS$OUTPUT.
LIB$RADIX_POINT | Radix point symbol.
LIB$REMQHI | Remove entry from head of queue.
LIB$REMQHIQ | Remove entry from head of queue. 1
LIB$REMQTI | Remove entry from tail of queue.
LIB$REMQTIQ | Remove entry from tail of queue. 1
LIB$RENAME_FILE | Rename one or more files.
LIB$RESERVE_EF | Reserve an event flag.
LIB$RESET_VM_ZONE | Reset virtual memory zone.
LIB$RESET_VM_ZONE_64 | Reset virtual memory zone. 1
LIB$REVERT | Revert to the handler of the procedure activator. 2 3
LIB$RUN_PROGRAM | Run new program.
LIB$SCANC | Scan for characters and return relative position.
LIB$SCOPY_DXDX | Copy source string by descriptor to destination.
LIB$SCOPY_R_DX | Copy source string by reference to destination.
LIB$SCOPY_R_DX_64 | Copy source string by reference to destination. 1
LIB$SET_LOGICAL | Set logical name.
LIB$SET_SYMBOL | Set the value of a CLI symbol.
LIB$SFREE1_DD | Free one or more dynamic strings.
LIB$SFREEN_DD | Free n dynamic strings.
LIB$SGET1_DD | Get one dynamic string.
LIB$SGET1_DD_64 | Get one dynamic string. 1
LIB$SHOW_TIMER | Show accumulated times and counts.
LIB$SHOW_VM | Show virtual memory statistics.
LIB$SHOW_VM_64 | Show virtual memory statistics. 1
LIB$SHOW_VM_ZONE | Display information about a virtual memory zone.
LIB$SHOW_VM_ZONE_64 | Display information about a virtual memory zone. 1
LIB$SIGNAL | Signal exception condition.
LIB$SIG_TO_RET | Convert a signaled message to a return status.
LIB$SIG_TO_STOP | Convert a signaled condition to a signaled stop.
LIB$SIM_TRAP | Simulate floating trap. 2
LIB$SKPC | Skip equal characters.
LIB$SPANC | Skip selected characters.
LIB$SPAWN | Spawn a subprocess.
LIB$STAT_TIMER | Return accumulated time and count statistics.
LIB$STAT_VM | Return virtual memory statistics.
LIB$STAT_VM_64 | Return virtual memory statistics. 1
LIB$STOP | Stop execution and signal the condition.
LIB$SUBX | Perform multiple-precision binary subtraction.
LIB$SUB_TIMES | Subtract two quadword times.
LIB$SYS_ASCTIM | Invoke $ASCTIM to convert binary time to ASCII.
LIB$SYS_FAO | Invoke $FAO system service to format output.
LIB$SYS_FAOL | Invoke $FAOL system service to format output.
LIB$SYS_FAOL_64 | Invoke $FAOL system service to format output. 1
LIB$SYS_GETMSG | Invoke $GETMSG system service to get message text.
LIB$TABLE_PARSE | Implement a table-driven, finite-state parser.
LIB$TPARSE | Implement a table-driven, finite-state parser. 2
LIB$TRAVERSE_TREE | Traverse a balanced binary tree.
LIB$TRAVERSE_TREE_64 | Traverse a balanced binary tree. 1
LIB$TRA_ASC_EBC | Translate ASCII to EBCDIC.
LIB$TRA_EBC_ASC | Translate EBCDIC to ASCII.
LIB$TRIM_FILESPEC | Fit a long file specification into a fixed field.
LIB$TRIM_FULLNAME | Trim a full name to fit into a desired output field.
LIB$VERIFY_VM_ZONE | Verify a virtual memory zone.
LIB$VERIFY_VM_ZONE_64 | Verify a virtual memory zone. 1
LIB$WAIT | Wait a specified period of time.

1Alpha specific.
2Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS Alpha systems.
3This routine or an equivalent mechanism is supplied by compilers on OpenVMS Alpha systems.
4VAX specific.

Next | Contents | Index

| privacy and legal statement |
5932PRO.HTML