OpenVMS RTL Library (LIB$) Manual

Updated: 07 June 2001

Order Number: AA-QSBHC-TE

January 1999

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.1 and OpenVMS VAX Version 7.1.

Software Version: OpenVMS Alpha Version 7.2 OpenVMS VAX Version 7.2

Compaq Computer Corporation
Houston, Texas

January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Bookreader, Compaq, DEC, DECdirect, DECmigrate, DECnet, DECtalk, DIGITAL, OpenVMS, PDP-11, VAX, VAX Ada, VAX BASIC, VAX DOCUMENT, VAX MACRO, VAXcluster, VMS, VMScluster, and the Compaq logo.

The following are third-party trademarks:

BASIC is a registered trademark of the Trustees of Dartmouth College, D.B.A. Dartmouth College.

CRAY is a registered trademark of Cray Research, Inc.

IBM is a registered trademark of International Business Machines Corporation.

IEEE is a registered trademark of The Institute of Electrical and Electronics Engineers, Inc.

Motif, OSF, OSF/1, and OSF/Motif are registered trademarks and Open Software Foundation is a trademark of the Open Software Foundation, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5932

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

This manual provides users of the 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 Interfaces: Calling a System Routine. 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 Interfaces: Calling a System Routine.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

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.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

In this manual, every use of DECwindows and DECwindows Motif refers to 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 elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

bold text This text style 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 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 Alpha Guide to 64-Bit Addressing and VLM Features 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.

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.

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.

LIB$CREATE_VM_ZONE Create a new storage zone.

++LIB$CREATE_VM_ZONE_64 Create a new storage zone.

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.

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. ¹

LIB$DEC_OVER Enable or disable decimal overflow detection. ¹

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.

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. ¹

LIB$EMUL Perform an extended-precision multiply.

LIB$ENABLE_CTRL Enable CLI interception of control characters.

LIB$ESTABLISH Establish a condition handler. ¹ ²

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.

LIB$FIT_NODENAME Fit a node name into an output field.

LIB$FIXUP_FLT Fix floating reserved operand. ¹

LIB$FLT_UNDER Detect a floating-point underflow. ¹

LIB$FORMAT_DATE_TIME Format a date and/or time.

+LIB$FORMAT_SOGW_PROT Format protection mask.

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.

LIB$FREE_VM_PAGE Free a virtual memory page.

++LIB$FREE_VM_PAGE_64 Free a virtual memory page.

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.

+LIB$GET_ACCNAM_BY_CONTEXT Get access name table for a security object identified by $GET_SECURITY or $SET_SECURITY context.

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.

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.

++LIB$GET_INVO_HANDLE Get invocation handle.

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.

++LIB$GET_PREV_INVO_HANDLE Get previous invocation handle.

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.

LIB$GET_VM_PAGE Get a virtual memory page.

++LIB$GET_VM_PAGE_64 Get a virtual memory page.

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.

LIB$INSQHI Insert entry at the head of a queue.

++LIB$INSQHIQ Insert entry at the head of a queue.

LIB$INSQTI Insert entry at the tail of a queue.

++LIB$INSQTIQ Insert entry at the tail of a queue.

LIB$INSV Insert a variable bit field.

LIB$INT_OVER Detect integer overflow. ¹

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.

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.

+LIB$PARSE_SOGW_PROT Parse protection string.

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. ¹

LIB$PUT_COMMON Put string into common area.

++LIB$PUT_INVO_REGISTERS Put invocation registers.

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.

LIB$REMQTI Remove entry from tail of queue.

++LIB$REMQTIQ Remove entry from tail of queue.

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.

LIB$REVERT Revert to the handler of the procedure activator. ¹ ²

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.

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.

LIB$SHOW_TIMER Show accumulated times and counts.

LIB$SHOW_VM Show virtual memory statistics.

++LIB$SHOW_VM_64 Show virtual memory statistics.

LIB$SHOW_VM_ZONE Display information about a virtual memory zone.

++LIB$SHOW_VM_ZONE_64 Display information about a virtual memory zone.

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. ¹

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.

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.

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. ¹

LIB$TRAVERSE_TREE Traverse a balanced binary tree.

++LIB$TRAVERSE_TREE_64 Traverse a balanced binary tree.

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.

LIB$WAIT Wait a specified period of time.

+VAX specific.
++Alpha specific.
¹Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS Alpha systems.
²This routine or an equivalent mechanism is supplied by compilers on OpenVMS Alpha systems.

Contents

Index