HP OpenVMS RTL Library (LIB$) Manual

Order Number: AA-QSBHE-TE

January 2005

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 HP OpenVMS RTL Library (LIB$) Manual, OpenVMS Alpha Version 7.3.

Software Version: OpenVMS I64 Version 8.2 OpenVMS Alpha Version 8.2

Hewlett-Packard Company
Palo Alto, California

Confidential computer software. Valid license from HP 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.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US

ZK5932

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

Contents Index

Preface

This manual provides users of the HP 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 HP 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 HP OpenVMS Programming Concepts Manual.

Reader's Comments

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

Internet openvmsdoc@hp.com

Mail Hewlett-Packard Company
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

For information on how to order additional documentation, visit the following World Wide Web address:

http://www.hp.com/go/openvms/doc/order

Conventions

In this manual, every use of DECwindows and DECwindows Motif refers to HP 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, Alpha, and HP OpenVMS Industry Standard 64 for Integrity Servers (I64) 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 or I64 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 HP 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 and I64 Only)

On Alpha and I64 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 HP 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. ¹

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$CVTS_FROM_INTERNAL_TIME Convert internal time to external time (IEEE S-floating value).

LIB$CVTF_TO_INTERNAL_TIME Convert external time to internal time (F-floating value).

LIB$CVTS_TO_INTERNAL_TIME Convert external time to internal time (IEEE S-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$EMODS Perform extended multiply and integerize for IEEE S-floating values.

LIB$EMODT Perform extended multiply and integerize for IEEE T-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$I64_CREATE_INVO_CONTEXT Allocate and initialize an invocation context block. ⁵

LIB$I64_GET_CURR_INVO_CONTEXT Get current invocation context. ⁵

LIB$I64_FREE_INVO_CONTEXT Deallocate an invocation context block. ⁵

LIB$I64_GET_CURR_INVO_HANDLE Get current invocation handle. ⁵

LIB$I64_GET_FR Get floating-point register value. ⁵

LIB$I64_GET_GR Get general register value. ⁵

LIB$I64_GET_INVO_HANDLE Get invocation handle. ⁵

LIB$I64_GET_INVO_CONTEXT Get invocation context. ⁵

LIB$I64_GET_PREV_INVO_CONTEXT Get previous invocation context. ⁵

LIB$I64_GET_PREV_INVO_END Free memory used to process unwind descriptors. ⁵

LIB$I64_GET_PREV_INVO_HANDLE Get previous invocation handle. ⁵

LIB$I64_GET_UNWIND_HANDLER_FV Given a pc_value, find the function value (address of the procedure descriptor) for the condition handler, if present, and write it to handler_fv. ⁵

LIB$I64_GET_UNWIND_LSDA Find Address of Unwind Information Block Language-Specific Data. ⁵

LIB$I64_GET_UNWIND_OSSD Find address of the unwind information block operating system-specific data area. ⁵

LIB$I64_INIT_INVO_CONTEXT Initialize an invocation context block that has already been allocated. ⁵

LIB$I64_IS_AST_DISPATCH_FRAME Determine whether a given PC value represents an AST dispatch frame. ⁵

LIB$I64_IS_EXC_DISPATCH_FRAME Determine whether a given PC value represents an exception dispatch frame. ⁵

LIB$I64_PUT_INVO_REGISTERS Update register contetnts using a given invocation context. ⁵

LIB$I64_PREV_INVO_END Free memory used tp process unwind descriptors. ⁵

LIB$I64_SET_FR Write context of invocation context block. ⁵

LIB$I64_SET_GR Write invocation block general register value. ⁵

LIB$I64_SET_PC Write pc_copy value of invocation context block. ⁵

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$LOCK Lock a specified image in the process's working set.

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$MULTS_DELTA_TIME Multiply delta time by IEEE S-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$POLYS Evaluate polynomials for IEEE S-floating values.

LIB$POLYT Evaluate polynomials for IEEE T-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$UNLOCK Unlock a specified image in the process's working set.

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.

**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$CVTS_FROM_INTERNAL_TIME	Convert internal time to external time (IEEE S-floating value).
LIB$CVTF_TO_INTERNAL_TIME	Convert external time to internal time (F-floating value).
LIB$CVTS_TO_INTERNAL_TIME	Convert external time to internal time (IEEE S-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$EMODS	Perform extended multiply and integerize for IEEE S-floating values.
LIB$EMODT	Perform extended multiply and integerize for IEEE T-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$I64_CREATE_INVO_CONTEXT	Allocate and initialize an invocation context block. ⁵
LIB$I64_GET_CURR_INVO_CONTEXT	Get current invocation context. ⁵
LIB$I64_FREE_INVO_CONTEXT	Deallocate an invocation context block. ⁵
LIB$I64_GET_CURR_INVO_HANDLE	Get current invocation handle. ⁵
LIB$I64_GET_FR	Get floating-point register value. ⁵
LIB$I64_GET_GR	Get general register value. ⁵
LIB$I64_GET_INVO_HANDLE	Get invocation handle. ⁵
LIB$I64_GET_INVO_CONTEXT	Get invocation context. ⁵
LIB$I64_GET_PREV_INVO_CONTEXT	Get previous invocation context. ⁵
LIB$I64_GET_PREV_INVO_END	Free memory used to process unwind descriptors. ⁵
LIB$I64_GET_PREV_INVO_HANDLE	Get previous invocation handle. ⁵
LIB$I64_GET_UNWIND_HANDLER_FV	Given a pc_value, find the function value (address of the procedure descriptor) for the condition handler, if present, and write it to handler_fv. ⁵
LIB$I64_GET_UNWIND_LSDA	Find Address of Unwind Information Block Language-Specific Data. ⁵
LIB$I64_GET_UNWIND_OSSD	Find address of the unwind information block operating system-specific data area. ⁵
LIB$I64_INIT_INVO_CONTEXT	Initialize an invocation context block that has already been allocated. ⁵
LIB$I64_IS_AST_DISPATCH_FRAME	Determine whether a given PC value represents an AST dispatch frame. ⁵
LIB$I64_IS_EXC_DISPATCH_FRAME	Determine whether a given PC value represents an exception dispatch frame. ⁵
LIB$I64_PUT_INVO_REGISTERS	Update register contetnts using a given invocation context. ⁵
LIB$I64_PREV_INVO_END	Free memory used tp process unwind descriptors. ⁵
LIB$I64_SET_FR	Write context of invocation context block. ⁵
LIB$I64_SET_GR	Write invocation block general register value. ⁵
LIB$I64_SET_PC	Write pc_copy value of invocation context block. ⁵
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$LOCK	Lock a specified image in the process's working set.
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$MULTS_DELTA_TIME	Multiply delta time by IEEE S-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$POLYS	Evaluate polynomials for IEEE S-floating values.
LIB$POLYT	Evaluate polynomials for IEEE T-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$UNLOCK	Unlock a specified image in the process's working set.
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.

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

Contents

Index

HP OpenVMS RTL Library (LIB$) Manual

January 2005

Preface

Intended Audience

Document Structure

Related Documents

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

Reader's Comments

How To Order Additional Documentation

Conventions

Part 1
LIB$ Overview Section

Chapter 1
Overview of the LIB$ Facility

1.1 Run-Time Library LIB$ Routines

1.1.1 64-Bit Addressing Support (Alpha and I64 Only)

1.1.2 The LIB$ Routines

Internet	openvmsdoc@hp.com
Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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.

HP OpenVMS RTL Library (LIB$) Manual

January 2005

Preface

Intended Audience

Document Structure

Related Documents

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

Reader's Comments

How To Order Additional Documentation

Conventions

Part 1LIB$ Overview Section

Chapter 1Overview of the LIB$ Facility

1.1 Run-Time Library LIB$ Routines

1.1.1 64-Bit Addressing Support (Alpha and I64 Only)

1.1.2 The LIB$ Routines

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

Part 1
LIB$ Overview Section

Chapter 1
Overview of the LIB$ Facility