(NETLIB Programmer's Guide) <ABSTRACT>(November, 1994) This manual contains information about NETLIB, a library for TCP/IP network programming on VMS systems. <ENDABSTRACT> <REVISION_INFO>(This is a new manual.) <REVISION_INFO>(Operating System and Version:\VAX/VMS V5.2 or later; OpenVMS AXP V1.0 or later) <REVISION_INFO>(Software Version:\NETLIB V2.0) <ENDTITLE_PAGE>(Matthew Madison<LINE>MadGoat Software) <COPYRIGHT_PAGE> <PRINT_DATE>(01 November 1994) Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. <emphasis>(DISCLAIMER:\bold) The author, the author's employer, and MadGoat Software make no representations or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. AXP, DEC, VAX, VMS, and OpenVMS are trademarks of Digital Equipment Corporation. UNIX is a trademark of Unix System Laboratories, Inc. MultiNet is a trademark of TGV, Inc. TCPware is a trademark of Process Software Corporation. PathWay is a trademark of The Wollongong Group, Inc. <COPYRIGHT_DATE>(1994\MadGoat Software. All Rights Reserved.) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <PREFACE>(\NETLIB_DOC_2) There are several TCP/IP packages available for VMS systems today. Each provides a VMS-style programming interface, using the $QIO system service, and most also provide a <quote>(socket) programming library, based on the communications model developed for BSD UNIX. Unfortunately, there is no standard among all of the packages for the $QIO-based programming interface (most, but not all, emulate Digital's, at least to some degree), and the $QIO-based interface is not very easy to use. The socket libraries provided with these packages provide a somewhat easier-to-use programming interface, but don't permit VMS-style asynchronous programming (using ASTs), and generally require at least a re-LINK, and sometimes source modifications, when moving from one vendor's library to another. NETLIB was originally developed to support MadGoat Software's Message Exchange mail package, which needed to support many TCP/IP packages doing VMS-style asynchronous programming. NETLIB provides a consistent, VMS-style interface for TCP/IP-based network programs, operating with all of the currently available TCP/IP packages available today for VMS (with one minor exception). In addition, NETLIB allows for flexibility in the use of a TCP/IP package, by selecting the vendor-dependent library code at run-time, rather than link-time. <head1>(Intended Audience\NETLIB_INST_3) This manual is intended for programmers writing applications that use NETLIB. <head1>(Document Structure\NETLIB_INST_4) This document consists of an introductory chapter, a section containing routine descriptions, and an appendix describing the status codes returned by NETLIB routines. <head1>(Related Documents\NETLIB_INST_5) The <emphasis>(NETLIB Installation Guide) describes how to install NETLIB. <endpreface> <ENDFRONT_MATTER> <CHAPTER>(Using NETLIB\NETLIB_DOC_3) This chapter discusses the NETLIB programming interface. <HEAD1>(Overview\NETLIB_DOC_4) NETLIB provides a single programming interface that can be used with almost any TCP/IP package for VMS systems. While every package provides a $QIO interface and most also provide a socket library, the advantages to using NETLIB instead are: <list>(unnumbered) <le>NETLIB allows VMS-style asynchronous programming (using ASTs) without having to use the $QIO interface directly. The $QIO programming interface varies from vendor to vendor. <le>NETLIB selects its vendor-specific support code at run-time, allowing you to switch between TCP/IP packages without re-linking your program. You can even have the same application, installed just once, run over different TCP/IP packages at the same time on different nodes in a VMScluster system. <le>NETLIB provides a VMS common language environment style of programming interface, making it easier to use from other languages than a UNIX-type socket library written for C programmers. <endlist> <head2>(NETLIB Services\NETLIB_DOC_5) NETLIB provides services for writing TCP/IP-based network programs, both client and server. Servers can either be standalone, AST-driven programs, or can be single-threaded server processes <quote>(forked) by the <quote>(master server) provided with each TCP/IP package. NETLIB services can be grouped into four basic areas: <list>(unnumbered) <le><emphasis>(Connection services\bold). These routines provide the services necessary for performing TCP/IP network I/O. <le><emphasis>(Line-mode services\bold). These routines provide a line-oriented network reads and writes, for line-oriented protocols that run over TCP. <le><emphasis>(DNS resolver services\bold). These routines provide host name and address lookup services. A direct DNS query routine is also provided. <le><emphasis>(Utility routines\bold). These are routines for doing byte-order conversions, IP address parsing and formatting, and other miscellaneous services. <endlist> <HEAD1>(Header files\NETLIB_DOC_6) NETLIB includes header files for both C and BLISS programming, called NETLIBDEF.H and NETLIBDEF.R32, respectively. The header files reside in the NETLIB_DIR: directory. These files define constants and structures that are used by the NETLIB programming interface. <HEAD1>(NETLIB Data Structures\NETLIB_DOC_7) NETLIB uses several data structures in its programming interface. Some of these data structures (INADDRDEF and SINDEF) are common to all BSD socket-oriented programming libraries, one (MXRRDEF) is special to NETLIB. The header files provided with NETLIB defines these structures for BLISS and C programmers. <HEAD2>(INADDRDEF Structure\NETLIB_DOC_8) The INADDRDEF structure is used for passing an IP address. The contents is (currently) a longword, in network byte order (see <reference>(byte_ordering) for more information). Its definition is (in C) is: <interactive> struct INADDRDEF { unsigned long inaddr_l_addr; } <endinteractive> <HEAD2>(SINDEF Structure\NETLIB_DOC_9) The SINDEF structure defines an IP <quote>(socket,) which is a combination of an IP address and a TCP or UDP port number. Its definition is: <interactive> struct SINDEF { unsigned short sin_w_family; unsigned short sin_w_port; struct INADDRDEF sin_x_addr; unsigned char sin_x_mbz[8]; } <endinteractive> <cp>The <emphasis>(sin_w_family\bold) field should always be set to NETLIB_K_AF_INET (value 2). The <emphasis>(sin_w_mbz\bold) field should always be zeroed. <cp>This is a specific form of the more general SOCKADDRDEF structure for use with IP-based sockets. NETLIB currently only supports IP network programming, so other types of addresses should not be used. <HEAD2>(MXRRDEF Structure\NETLIB_DOC_10) The MXRRDEF structure is used to return MX resource record information in a call to NETLIB_DNS_MX_LOOKUP: <interactive> struct MXRRDEF { unsigned int mxrr_l_preference; unsigned int mxrr_l_length; char mxrr_t_name[128]; } <endinteractive> This structure is NETLIB-specific. <HEAD2>(NETLIB_DNS_HEADER Structure\NETLIB_DOC_11) A domain name server accepts queries and returns replies prefixed with with a standard header. A definition of this header is provided in the NETLIB_DNS_HEADER structure. Refer to the NETLIBDEF header file and the appropriate DNS RFCs (such as RFC 1035) for more information about this header. Only those programs which use the NETLIB_DNS_QUERY routine will need this header definition. <HEAD1>(Byte-Order Considerations\byte_ordering) In NETLIB routines, addresses and port numbers are expected to be in <quote>(network order;) that is, with the high-order byte first. This is opposite the natural byte-order for VAX and AXP systems running VMS, which places the low-order byte first. NETLIB provides routines that can be used to reverse byte order for use in the calls which expect it. <HEAD1>(Synchronous vs. Asynchronous Operation\NETLIB_DOC_12) Most NETLIB routines can be executed synchronously (where the routine uses $QIOW) or asynchronously ($QIO is used instead of $QIOW). To have a routine called asynchronously, specify a non-zero <emphasis>(astadr\bold) argument (and, optionally, the <emphasis>(astprm\bold) argument, to have a parameter passed to the AST routine). <HEAD1>(I/O Status Block\NETLIB_DOC_13) Most NETLIB routines include an optional parameter for a VMS-style I/O status block (IOSB), which is used to return status information to the calling program. The first word of the IOSB is the NETLIB status code for the call; the second word, for read and write operations, is the number of bytes transferred. The second longword of the IOSB is not used by NETLIB. <HEAD1>(Linking NETLIB Programs\NETLIB_DOC_14) To link your program with NETLIB, include the following line in a LINK options file: <interactive> NETLIB_SHRXFR/SHARE <endinteractive> Referencing this logical name will link your program against NETLIB's transfer vector, which at run-time will activate the appropriate vendor-specific version of NETLIB (pointed to by the NETLIB_SHR logical name). <HEAD1>(Contacting the Author\NETLIB_DOC_15) There is no formal support for NETLIB. If you have Internet connectivity, however, you may wish to subscribe to one or more of the following MadGoat Software mailing lists: <list>(simple) <le><emphasis>(Info-MadGoat@wkuvx1.wku.edu\bold) Discussion of MadGoat Software products by users and MadGoat developers. To subscribe, send a message to <emphasis>(Info-MadGoat-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Announce@wkuvx1.wku.edu\bold) Announcements of new releases and new products from MadGoat. To subscribe, send a message to <emphasis>(MadGoat-Announce-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Bugs@wkuvx1.wku.edu\bold) Address for reporting bugs in MadGoat Software products. Please include the name of the package and version in the subject header of the message, so the report can be more easily directed to the appropriate developer. <endlist> <part>(Routine Descriptions\rtnpart) <part_page> <title>(<reference>(rtnpart)\<reference>(rtnpart\text)) <abstract> This part describes the each of the NETLIB routines. <endabstract> <endpart_page>(renumber) <routine_section>(NETLIB Routines\RTN) <set_template_heading>(rsdeflist\CONDITION VALUES RETURNED) <comment>(----------------------------------------------------------------) <routine>(NETLIB_ACCEPT\Accept an incoming connection\\NETLIB_DOC_16) <overview> NETLIB_ACCEPT waits for an incoming connection and accepts it, creating a new socket for the new connection. <endoverview> <format> <frtn>(NETLIB_ACCEPT) <fargs>(socket ,newsocket [,remaddr] [,remaddr-size] [,remaddr-len] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket that was established as a listener. <argitem>(newsocket\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Socket for the accepted connection (created and returned by this routine). <argitem>(remaddr\structure\longword (unsigned)\write only\by reference) <argdef>Address of a socket_address structure into which the remote address/port information for the new connection is written. <argitem>(remaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the <emphasis>(remaddr\bold) structure. <argitem>(remaddr-len\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Longword into which the actual returned lenght of the socket address is written. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used as part of a <quote>(passive) open sequence, typically by servers that bind a socket to a specific port number, then establish a listener to handle the incoming connections. This call is used to accept an incoming connection, creating a new socket for the new connection. The listener socket is not affected by this call, so you can call NETLIB_ACCEPT again to wait for another incoming connection on the same port after one accept completes. If you want to know the address and port number of the remote end of the accepted connection, you can either use the <emphasis>(remaddr\bold), <emphasis>(remaddr-size\bold), and <emphasis>(remaddr-len\bold) arguments on this call, or follow this call with a call to NETLIB_GETPEERNAME. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_ADDRESS_TO_NAME\Get the host name for an IP address\\NETLIB_DOC_17) <overview> NETLIB_ADDRESS_TO_NAME performs an inverse host lookup, returning a name associated with an IP address. <endoverview> <format> <frtn>(NETLIB_ADDRESS_TO_NAME) <fargs>(socket, [which], address, addrsize, hostname [,retlen] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket about which you wish to obtain the option information. <argitem>(which\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A code indicating the type of lookup to be performed. Possible values are NETLIB_K_LOOKUP_DNS (1), which requests that the name be looked up using the Domain Name System, and NETLIB_K_LOOKUP_HOST_TABLE (2), which requests that the name be looked up in the local host table. If omitted, the default is NETLIB_K_LOOKUP_DNS. See the Description section for information on package-specific restrictions with this parameter. <argitem>(address\structure\longword (unsigned)\read only\by reference) <argdef>An INADDRDEF structure containing the address to be looked up. <argitem>(addrsize\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The size of the address passed in the <emphasis>(address\bold) parameter. <argitem>(hostname\char_string\character string\write only\by descriptor) <argdef>A buffer into which the returned host name will be written. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The returned length of the host name, in bytes. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine performs an address-to-name lookup on the specified IP address. Each TCP/IP package implements this function slightly differently, so there are some restrictions on the use of this routine. For MultiNet, TCPware, and Pathway, the <emphasis>(which\bold) argument is used to determine whether the lookup should occur using NETLIB's DNS resolver support or using the TCP/IP package's host-table access routines. For these packages, the host-table access method cannot be used at AST level. Also, if a DNS lookup is attempted and the system is not configured for DNS, an SS$_UNSUPPORTED error will be returned. For UCX and CMU TCP/IP, the <emphasis>(which\bold) argument is ignored, since these packages do not provide separate access to DNS and local host tables. For UCX, host table lookup will occur first, followed by a DNS lookup. For CMU, this order is reversed. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_ADDRTOSTR\Format an IP address to a string\\NETLIB_DOC_18) <overview> NETLIB_ADDRTOSTR is a utility routine for formatting an IP address as a character string. <endoverview> <format> <frtn>(NETLIB_ADDRTOSTR) <fargs>(address, string [,retlen]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(address\INADDRDEF structure\longword (unsigned)\read only\by reference) <argdef>An INADDRDEF structure containing the address to be formatted. <argitem>(string\char_string\character string\write only\by descriptor) <argdef>The string to hold the formatted address. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The number of characters written to <emphasis>(string\bold). <endargdeflist> <description> This is a utility routine which formats an IP address to a character string, using the dotted-decimal format. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_BIND\Bind a socket to an address/port\\NETLIB_DOC_19) <overview> NETLIB_BIND sets the address and/or port number for a socket. <endoverview> <format> <frtn>(NETLIB_BIND) <fargs>(socket, socket-address, sockaddr-len [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be bound. <argitem>(socket-address\structure\longword (unsigned)\read only\by reference) <argdef>Socket_address structure describing the addreses and port to which the socket is to be bound. <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used primarily by server programs to bind a socket to a particular port, and is typically followed by a call to NETLIB_LISTEN to open a passive connection on that port. If a program does not bind a socket to a particular local address/port combination, the underlying TCP/IP software will automatically assign an address and/or port. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_CLOSE\Close down a socket\\NETLIB_DOC_20) <overview> NETLIB_CLOSE closes a socket. <endoverview> <format> <frtn>(NETLIB_CLOSE) <fargs>(socket) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be closed. <endargdeflist> <description> This routine deletes the specified socket, closing the associated network communications channel, if one is open. Once closed, the socket can no longer be used; you must open a new one with the NETLIB_SOCKET call. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_CONNECT\Connect a socket to a remote address/port\\NETLIB_DOC_21) <overview> NETLIB_CONNECT connects a socket to a remote address/port. <endoverview> <format> <frtn>(NETLIB_CONNECT) <fargs>(socket, socket-address, sockaddr-len [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be connected. <argitem>(socket-address\structure\longword (unsigned)\read only\by reference) <argdef>Socket_address structure describing the addreses and port to which the socket is to be connected. <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used primarily with TCP-based programs to establish a connection to a remote system. When used with UDP, this routine fixes the address to which subsequent UDP datagrams will be sent. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_CONNECT_BY_NAME\Establish a TCP connection to a host by name\\NETLIB_DOC_22) <overview> NETLIB_CONNECT_BY_NAME establishes a TCP connection to a host using the host's name, rather than its IP address. <endoverview> <format> <frtn>(NETLIB_CONNECT_BY_NAME) <fargs>(socket, hostname, port [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A STREAM-type socket allocated with NETLIB_SOCKET. <argitem>(hostname\char_string\character string\read only\by descriptor) <argdef>A character string containing either a host name or an IP address in dotted-decimal format. <argitem>(port\word_unsigned\word (unsigned)\read only\by reference) <argdef>The port number to connect to on the destination host. Unlike the SIN_W_PORT field of a SINDEF (socket address) structure, this number is specified in <emphasis>(host order), not network order. NETLIB_CONNECT_BY_NAME will automatically convert the port number to network order for you. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine converts the specified name or dotted-decimal address to an IP address and uses NETLIB_CONNECT to connect to the specified host and port. If multiple addresses are returned by the host name lookup, each address will be tried until a connection is established or all addresses have been tried. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_EXPANDNAME\Expand a name in a DNS response\\NETLIB_DOC_23) <overview> NETLIB_DNS_EXPANDNAME is a utility routine used for extracting a domain name from a DNS response. <endoverview> <format> <frtn>(NETLIB_DNS_EXPANDNAME) <fargs>(bufstart, buflen, bufptr, name [,retlen] [,skipcount]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(bufstart\pointer\longword (unsigned)\read only\by value) <argdef>A pointer to the start of the DNS response buffer. <argitem>(buflen\word_unsigned\word (unsigned)\read only\by reference) <argdef>The size of the buffer, in bytes. <argitem>(bufptr\pointer\longword (unsigned)\read only\by value) <argdef>A pointer to the area of the buffer containing the domain name to be expanded. <argitem>(name\char_string\character string\write only\by descriptor) <argdef>A descriptor for a character string buffer into which the expanded name will be written. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The returned length of the expanded name, in bytes. <argitem>(skipcount\word_unsigned\word (unsigned)\write only\by reference) <argdef>The number of bytes in the buffer that were used for the domain name. <endargdeflist> <description> This is a utility routine used when parsing a response returned by a call to NETLIB_DNS_QUERY. It expands a domain name stored in a DNS response out to the typical, human-readable, dotted-domain format. This routine is needed because of the way domain names are represented in DNS responses. Refer to RFC 1035 for further information on the format of DNS queries and responses. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_MX_LOOKUP\Look up MX records for a domain name\\NETLIB_DOC_24) <overview> NETLIB_DNS_MX_LOOKUP looks up a host name, returning any MX records. <endoverview> <format> <frtn>(NETLIB_DNS_MX_LOOKUP) <fargs>(socket, hostname, mxrrlist, mxrrlist-size [,mxrrcount] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Any socket allocated with NETLIB_SOCKET. <argitem>(hostname\char_string\character string\read only\by descriptor) <argdef>The host name to be looked up. <argitem>(mxrrlist\array of structures\longword (unsigned)\write only\by reference) <argdef>An array of MXRRDEF structures into which the MX records will be written. <argitem>(mxrrlist-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The number of elements in the <emphasis>(mxrrlist\bold) array. <argitem>(mxrrcount\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>The actual number of MX records written to <emphasis>(mxrrlist\bold). <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine performs a DNS lookup on the specified name, returning any Mail Exchanger (MX) records for that name. For MultiNet, TCPware, and Pathway, and UCX, this routine is a front-end that uses NETLIB_DNS_QUERY to perform the DNS queries. For CMU TCP/IP, the MX lookups are performed using NAMRES calls. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_QUERY\Perform a DNS query\\NETLIB_DOC_25) <overview> NETLIB_DNS_QUERY formats a domain name service query and returns the response from a DNS server. <endoverview> <format> <frtn>(NETLIB_DNS_QUERY) <fargs>(socket, name, [class], type, buffer, bufsize [,flags] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A socket allocated with NETLIB_SOCKET. Any socket can be used. <argitem>(name\char_string\character string\read only\by descriptor) <argdef>The domain name to be looked up. <argitem>(class\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The class of the query. For Internet domain names, this should be NETLIB_K_DNS_CLASS_IN, which is the default if this parameter is omitted. <argitem>(type\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The type of query. Valid type codes are specified by Internet RFCs on the DNS, the codes provided by NETLIB are listed in <reference>(dns_types). <table>(Domain Name Service query types\dns_types) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_DNS_TYPE_A\1\Address (A) records) <table_row>(NETLIB_K_DNS_TYPE_NS\2\Name Server (NS) records) <table_row>(NETLIB_K_DNS_TYPE_CNAME\5\Canonical Name (CNAME) records) <table_row>(NETLIB_K_DNS_TYPE_SOA\6\Start-of-Authority (SOA) records) <table_row>(NETLIB_K_DNS_TYPE_WKS\11\Well-known-server (WKS) records) <table_row>(NETLIB_K_DNS_TYPE_PTR\12\Pointer (PTR) records) <table_row>(NETLIB_K_DNS_TYPE_HINFO\13\Host information (HINFO) records) <table_row>(NETLIB_K_DNS_TYPE_MX\15\Mail Exchanger (MX) records) <table_row>(NETLIB_K_DNS_TYPE_TXT\16\Text (TXT) records) <table_row>(NETLIB_K_DNS_QTYPE_ALL\255\Any available information) <endtable> <argitem>(buffer\varying_arg\longword (unsigned)\write only\by reference) <argdef>A buffer into which the DNS response will be copied. <argitem>(bufsize\word_unsigned\word (unsigned)\read only\by reference) <argdef>The size of <emphasis>(buffer\bold), in bytes. <argitem>(flags\longword_mask\longword (unsigned)\read only\by reference) <argdef>A bitmask of flags specifying options for this query. Valid flags are listed in <reference>(query_flags). If omitted, the default value for this parameter is 1. <table>(Flag values for NETLIB_DNS_QUERY\query_flags) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_M_DOMAIN_SEARCH\1\Perform a domain search on the default domain.) <table_row>(NETLIB_M_NO_RECURSION\2\Specify a non-recursive query.) <endtable> <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine formats a DNS query and returns the response from any answering name server. If the query fails, an error status is returned. For MultiNet, TCPware, and Pathway, and UCX, the name servers that are queried are those specified for those packages. With MultiNet, for example, the ones listed in the translation string for the logical name for MULTINET_NAMESERVERS are used. For the CMU TCP/IP package, the name servers used by NAMRES are not available to NETLIB, so you must define the logical name NETLIB_NAMESERVERS with the IP address(es) of the name server(s) you want NETLIB to use. If no name servers can be found, SS$_UNSUPPORTED is returned. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_SKIPNAME\Skip a name in a DNS response\\NETLIB_DOC_26) <overview> NETLIB_DNS_SKIPNAME is a utility routine used for parsing DNS responses which skips over a domain name. <endoverview> <format> <frtn>(NETLIB_DNS_SKIPNAME) <fargs>(bufptr, buflen) <endformat> <returns>(longword_signed\longword (signed)\write only\by value) <argdeflist> <argitem>(bufptr\pointer\longword (unsigned)\read only\by value) <argdef>A pointer to the area of the DNS response buffer that begins the name to be skipped. <argitem>(buflen\word_unsigned\word (unsigned)\read only\by reference) <argdef>A count of the number of bytes in the buffer, starting from <emphasis>(bufptr\bold). <endargdeflist> <description> This is a utility routine used when parsing a response returned by a call to NETLIB_DNS_QUERY. It returns a count of the number of bytes to skip allocated to the domain name positioned in the buffer at location <emphasis>(bufptr\bold). If the operation fails, -1 is returned to indicate an error. This routine is needed because of the way domain names are represented in DNS responses. Refer to RFC 1035 for further information on the format of DNS queries and responses. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_GETPEERNAME\Get remote socket address\\NETLIB_DOC_27) <overview> NETLIB_GETSOCKNAME returns the remote address and port information for a connected socket. <endoverview> <format> <frtn>(NETLIB_GETPEERNAME) <fargs>(socket, socket-address, sockaddr-size, sockaddr-retlen [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket for which the information is to be returned. <argitem>(socket-address\structure\longword (unsigned)\write only\by reference) <argdef>Socket_address structure which will hold the returned address/port information. <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(sockaddr-retlen\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Returned actual length of the socket address. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used to return the remote address and port information for a socket that is connected to a remote system. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_GETSOCKNAME\Get local socket address\\NETLIB_DOC_28) <overview> NETLIB_GETSOCKNAME returns the local address and port information for a socket. <endoverview> <format> <frtn>(NETLIB_GETSOCKNAME) <fargs>(socket, socket-address, sockaddr-size, sockaddr-retlen [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket for which the information is to be returned. <argitem>(socket-address\structure\longword (unsigned)\write only\by reference) <argdef>Socket_address structure which will hold the returned address/port information. <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(sockaddr-retlen\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Returned actual length of the socket address. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used to return the local address and port information for a socket that has been bound or connected. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_GETSOCKOPT\Get socket options\\NETLIB_DOC_29) <overview> NETLIB_GETSOCKOPT gets the current state of a socket option. <endoverview> <format> <frtn>(NETLIB_GETSOCKOPT) <fargs>(socket, level, option, value, valsize [,vallen] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket about which you wish to obtain the option information. <argitem>(level\longword_unsigned\longword (unsigned)\read only\by reference) <argdef><quote>(Level) of the option being set. The only level globally supported is NETLIB_K_LEVEL_SOCKET (value X'FFFF'). Some packages also support protocol-level option settings. <argitem>(option\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Longword representing the option being set. Not all packages support all options, but most support the ones listed in <reference>(option_table). Consult your package-specific documentation on other available options and on option value ranges. The CMU TCP/IP package is not based on sockets, so this call will always return success status with 0 returned length on systems running that package. <argitem>(value\varying_arg\longword (unsigned)\write only\by reference) <argdef>Value to set for the option. Values vary from option to option. <argitem>(valsize\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the <emphasis>(value\bold) argument, in bytes. <argitem>(vallen\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Actual returned length of <emphasis>(value\bold), in bytes. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine provides an interface to the <emphasis>(getsockopt\bold) service provided by most TCP/IP packages (most are based on the BSD socket communications model). Note that not all options are available with all packages, and for the CMU TCP/IP this call is a no-operation -- it will always return a success status, with 0 as the returned length of the option value. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_HTON_LONG\Convert host-order longword to network order\\NETLIB_DOC_30) <overview> NETLIB_HTON_LONG is a utility routine for converting a longword in the local host's byte order to a network-order longword. <endoverview> <format> <frtn>(NETLIB_HTON_LONG) <fargs>(value) <endformat> <returns>(longword_unsigned\longword (unsigned)\write only\by value) <argdeflist> <argitem>(value\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The longword to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a longword to convert it from the native format for the local host (which is <quote>(little-endian) for VAX and AXP systems running VMS) to network order (which is <quote>(big-endian)). The returned value is the network-order longword. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_HTON_WORD\Convert host-order word to network order\\NETLIB_DOC_31) <overview> NETLIB_HTON_WORD is a utility routine for converting a word in the local host's byte order to a network-order word. <endoverview> <format> <frtn>(NETLIB_HTON_WORD) <fargs>(value) <endformat> <returns>(word_unsigned\word (unsigned)\write only\by value) <argdeflist> <argitem>(value\word_unsigned\word (unsigned)\read only\by reference) <argdef>The word to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a word to convert it from the native format for the local host (which is <quote>(little-endian) for VAX and AXP systems running VMS) to network order (which is <quote>(big-endian)). The return value is the network-order word. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_LISTEN\Listen for incoming connections\\NETLIB_DOC_32) <overview> NETLIB_LISTEN sets a socket up to listen for incoming connections. <endoverview> <format> <frtn>(NETLIB_LISTEN) <fargs>(socket [,backlog] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be set up as a listener. <argitem>(backlog\unsigned int\longword (unsigned)\read only\by reference) <argdef>The number of backlogged connections to allow on this listener. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used as part of a <quote>(passive) open sequence, typically by servers that bind a socket to a specific port number, then establish a listener to handle the incoming connections. This call is usually followed by one or more invocations of NETLIB_ACCEPT to accept the incoming connections. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_NAME_TO_ADDRESS\Get the IP address(es) for a host name\\NETLIB_DOC_33) <overview> NETLIB_NAME_TO_ADDRESS looks up a host name, returning its IP address(es). <endoverview> <format> <frtn>(NETLIB_NAME_TO_ADDRESS) <fargs>(socket, [which], hostname, addrlist, addrlist-size [,addrcount] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket about which you wish to obtain the option information. <argitem>(which\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A code indicating the type of lookup to be performed. Possible values are NETLIB_K_LOOKUP_DNS (1), which requests that the name be looked up using the Domain Name System, and NETLIB_K_LOOKUP_HOST_TABLE (2), which requests that the name be looked up in the local host table. If omitted, the default is NETLIB_K_LOOKUP_DNS. See the Description section for information on package-specific restrictions with this parameter. <argitem>(hostname\char_string\character string\read only\by descriptor) <argdef>The host name to be looked up. <argitem>(addrlist\array of structures\longword (unsigned)\write only\by reference) <argdef>An array of INADDRDEF structures into which the addresses will be written. <argitem>(addrlist-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The number of elements in the <emphasis>(addrlist\bold) array. <argitem>(addrcount\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>The actual number of addresses written to <emphasis>(addrlist\bold). <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine performs a name-to-address lookup on the specified host name. Each TCP/IP package implements this function slightly differently, so there are some restrictions on the use of this routine. For MultiNet, TCPware, and Pathway, the <emphasis>(which\bold) argument is used to determine whether the lookup should occur using NETLIB's DNS resolver support or using the TCP/IP package's host-table access routines. For these packages, the host-table access method cannot be used at AST level. Also, if a DNS lookup is attempted and the system is not configured for DNS, an SS$_UNSUPPORTED error will be returned. For UCX and CMU TCP/IP, the <emphasis>(which\bold) argument is ignored, since these packages do not provide separate access to DNS and local host tables. For UCX, host table lookup will occur first, followed by a DNS lookup. For CMU, this order is reversed. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_NTOH_LONG\Convert network-order longword to host order\\NETLIB_DOC_34) <overview> NETLIB_NTOH_LONG is a utility routine for converting a longword in the network byte order to a host-order longword. <endoverview> <format> <frtn>(NETLIB_NTOH_LONG) <fargs>(value) <endformat> <returns>(longword_unsigned\longword (unsigned)\write only\by value) <argdeflist> <argitem>(value\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The longword to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a longword to convert it from network order to host order. The return value is the host-order longword. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_NTOH_WORD\Convert network-order word to host order\\NETLIB_DOC_35) <overview> NETLIB_NTOH_WORD is a utility routine for converting a word in the network byte order to a host-order word. <endoverview> <format> <frtn>(NETLIB_NTOH_WORD) <fargs>(value) <endformat> <returns>(word_unsigned\word (unsigned)\write only\by value) <argdeflist> <argitem>(value\word_unsigned\word (unsigned)\read only\by reference) <argdef>The word to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a word to convert it from network order to host order. The return value is the host-order word. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_READ\Receive data from remote system\\NETLIB_DOC_36) <overview> NETLIB_READ reads data sent by a remote system from a socket. <endoverview> <format> <frtn>(NETLIB_READ) <fargs>(socket, buffer [,socket-address] [,sockaddr-size] [,sockaddr-len] [,timeout] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to which data should be written. <argitem>(buffer\unspecified\longword (unsigned)\write only\by descriptor (fixed-length)) <argdef>The address of a descriptor for a buffer to receive the data. <argitem>(socket-address\structure\longword (unsigned)\write only\by reference) <argdef>Socket_address structure to receive the addreses and port from which the data is to be sent. Typically used only with unconnected UDP sockets). <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. Typically used only with unconnected UDP sockets. <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Returned length of the socket address structure. Typically used only with unconnected UDP sockets. <argitem>(timeout\delta_time\quadword (signed)\read only\by reference) <argdef>Amount of time that NETLIB_READ should wait for the read to complete. If omitted, no timeout is used. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine reads data from the socket into the specified buffer. The read will complete when the buffer is full, or if the read times out (if <emphasis>(timeout\bold) is specified). A fixed-length descriptor should be used for the buffer. To obtain the actual number of bytes read in this call, use an I/O status block. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_READLINE\Read a <quote>(line) of data\\NETLIB_DOC_37) <overview> NETLIB_READLINE reads a <quote>(line) of data from the socket. <endoverview> <format> <frtn>(NETLIB_READLINE) <fargs>(socket, buffer [,retlen] [,flags] [,timeout] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket from which data should be read. <argitem>(buffer\char_string\character string\write only\by descriptor) <argdef>The address of a descriptor for the buffer to hold the line. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The address of a word which receives the actual length of the received line. <argitem>(flags\bitmask\longword (unsigned)\read only\by reference) <argdef>The address of a bitmask containing flags controlling this call. Only one flag is currently defined, NETLIB_M_ALLOW_LF (value 1), which causes NETLIB_READLINE to consider either a CR/LF pair or a bare LF as a line terminator. If this argument is omitted, this flag is enabled by default. Otherwise, only a CR/LF pair will be considered a line terminator. <argitem>(timeout\delta_time\quadword (signed)\read only\by reference) <argdef>The address of a VMS delta time value specifying the timeout for this read. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is intended for TCP-based programs that use a protocol which delimits commands and replies with carriage-return/linefeed pairs. It completes only when the specified buffer is full; when a complete, terminated, line has been received; or if a timeout occurs. The line terminator is stripped from the returned data. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SERVER_SETUP\Socket setup for <quote>(forked) servers\\NETLIB_DOC_38) <overview> NETLIB_SERVER_SETUP creates and sets up the socket used by a server process <quote>(forked) from a TCP/IP package's <quote>(master server). <endoverview> <format> <frtn>(NETLIB_SERVER_SETUP) <fargs>(socket, socket-address, sockaddr-size) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Returned socket handle for use in subsequent NETLIB calls. <argitem>(socket-address\special_structure\longword (unsigned)\read only\by reference) <argdef>Socket address describing port being opened. See note in description section. <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the structure passed in <emphasis>(socket-address\bold) argument. <endargdeflist> <description> This routine creates a NETLIB socket for the communications channel in a server program invoked by a TCP/IP package's <quote>(master server.) The <emphasis>(socket-address\bold) and <emphasis>(sockaddr-size\bold) arguments must be provided, although for all packages except CMU TCP/IP they are ignored (the actual address and port number are pre-determined). <NOTE> For at least some TCP/IP packages, this routine should be called <emphasis>(before) any language-specific I/O routines (for example, the <emphasis>(printf\bold) routine in the C run-time library) are called, to prevent the run-time system from interfering with the network channel. <ENDNOTE> <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SETSOCKOPT\Set socket options\\NETLIB_DOC_39) <overview> NETLIB_SETSOCKOPT modifies attributes of a a socket. <endoverview> <format> <frtn>(NETLIB_SETSOCKOPT) <fargs>(socket, level, option, value, vallen [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket you wish to modify. <argitem>(level\longword_unsigned\longword (unsigned)\read only\by reference) <argdef><quote>(Level) of the option being set. The only level globally supported is NETLIB_K_LEVEL_SOCKET (value X'FFFF'). Some packages also support protocol-level option settings. <argitem>(option\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Longword representing the option being set. Not all packages support all options, but most support the ones listed in <reference>(option_table). <table>(Socket options\option_table) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_OPTION_REUSEADDR\4\Allows a port number to be reused. Value is a longword, either 1 (on) or 0 (off). Default for most packages is off, but NETLIB turns this option on automatically unless you explicitly call NETLIB_SETSOCKOPT to set it.) <table_row>(NETLIB_K_OPTION_SNDBUF\4097\Sets socket buffer size for sends. Value is a longword, typically with a maximum value of 32768.) <table_row>(NETLIB_K_OPTION_RCVBUF\4098\Sets socket buffer size for receives. Value is a longword, typically with a maximum value of 32768.) <endtable> Consult your package-specific documentation on other available options and on option value ranges. The CMU TCP/IP package is not based on sockets, so this call has no effect on systems running that package. <argitem>(value\varying_arg\longword (unsigned)\read only\by reference) <argdef>Value to set for the option. Values vary from option to option. <argitem>(vallen\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the <emphasis>(value\bold) argument, in bytes. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine provides an interface to the <emphasis>(setsockopt\bold) service provided by most TCP/IP packages (most are based on the BSD socket communications model). Note that not all options are available with all packages, and for the CMU TCP/IP this call is a no-operation. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SHUTDOWN\Shut down a connection\\NETLIB_DOC_40) <overview> NETLIB_SHUTDOWN shuts down a connection without deleting the socket. <endoverview> <format> <frtn>(NETLIB_SHUTDOWN) <fargs>(socket [,shuttype] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be set up as a listener. <argitem>(shuttype\unsigned int\longword (unsigned)\read only\by reference) <argdef>Type of shutdown to be performed. Possible values are listed in <reference>(shut_table). If omitted, the default is NETLIB_K_SHUTDOWN_RECEIVER. <table>(Shutdown types\shut_table) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_SHUTDOWN_RECEIVER\0\Prevent any further receives.) <table_row>(NETLIB_K_SHUTDOWN_SENDER\1\Prevent any further sends.) <table_row>(NETLIB_K_SHUTDOWN_BOTH\2\Prevent any further sends/receives.) <endtable> This parameter has no meaning when using the CMU TCP/IP package. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine closes the network connection currently open on the specified socket, without deleting the socket. Any data still waiting to be received or sent can be discarded or retained by specifying an appropriate shutdown type in <emphasis>(shuttype\bold). For the CMU TCP/IP package, the shutdown type is not used; the CMU close operation does not provide this option. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SOCKET\Create a NETLIB communication endpoint\\NETLIB_DOC_41) <overview> NETLIB_SOCKET creates a <quote>(socket) -- that is, a local endpoint for TCP/IP communication. <endoverview> <format> <frtn>(NETLIB_SOCKET) <fargs>(socket [,socket-type] [,socket-family]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>The returned socket context, for use in subsequent NETLIB calls. <argitem>(socket-type\longword_unsigned \longword (unsigned)\read only\by referencee) <argdef>Type of socket to be created. Allowed values are shown in <reference>(socket_type_table). If omitted, the default is NETLIB_K_TYPE_STREAM. <table>(Socket types\socket_type_table) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_TYPE_STREAM\1\Connection-oriented socket (for TCP).) <table_row>(NETLIB_K_TYPE_DGRAM\2\Connectionless socket (for UDP).) <endtable> <argitem>(socket-family\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Address/protocol family. Only NETLIB_K_AF_INET (value 2) is permitted, and is assumed by default if omitted. <endargdeflist> <description> This routine creates a <quote>(socket) (an endpoint for network communication). One socket is required for each network connection. This will be the first call in most NETLIB-based programs. The only exception to this rule is a program that is intended to be run as a <quote>(forked) server from a TCP/IP package's <quote>(master server), which will use the NETLIB_SERVER_SETUP routine instead. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_STRTOADDR\Convert a dotted-address to binary form\\NETLIB_DOC_42) <overview> NETLIB_STRTOADDR is a utility routine for converting a character string holding a dotted-decimal IP addreses into its binary equivalent. <endoverview> <format> <frtn>(NETLIB_STRTOADDR) <fargs>(string, address) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(string\char_string\character string\read only\by descriptor) <argdef>The string containing the dotted-decimal address. <argitem>(address\INADDRDEF structure\longword (unsigned)\write only\by reference) <argdef>An INADDRDEF structure to hold the returned address. <endargdeflist> <description> This is a utility routine which parses a character string containing an IP address in dotted-decimal format, returning the binary representation of that address in network order (suitable for a call to NETLIB_CONNECT, for example). <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_WRITE\Send data to remote system\\NETLIB_DOC_43) <overview> NETLIB_WRITE writes data to a socket for transmission to a remote system. <endoverview> <format> <frtn>(NETLIB_WRITE) <fargs>(socket, buffer [,socket-address] [,sockaddr-len] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to which data should be written. <argitem>(buffer\unspecified\longword (unsigned)\read only\by descriptor) <argdef>The address of a descriptor for the data to be sent. <argitem>(socket-address\structure\longword (unsigned)\read only\by reference) <argdef>Socket_address structure describing the addreses and port to which the data is to be sent. Used only with unconnected UDP sockets). <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. Used only with unconnected UDP sockets. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine writes the specified data to the socket for transmission to the remote system. For UDP sockets that have not been connected to a specific remote address, the <emphasis>(socket-address\bold) argument specifies the remote address/port to which the datagram is to be sent. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_WRITELINE\Send data with CR/LF termination\\NETLIB_DOC_44) <overview> NETLIB_WRITELINE writes data to a socket for transmission to a remote system, terminating the data with a CR/LF pair. <endoverview> <format> <frtn>(NETLIB_WRITELINE) <fargs>(socket, buffer [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to which data should be written. <argitem>(buffer\char_string\character string\read only\by descriptor) <argdef>The address of a descriptor for the data to be sent. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine functions identically to NETLIB_WRITE, but adds a carriage-return/ linefeed pair to the data sent to the remote system. It is intended for TCP-based programs that use a protocol which delimits commands and responses with CR/LFs. <enddescription> <endroutine_section> <APPENDIX>(Status Codes\status_codes) NETLIB translates all TCP/IP status codes into the codes used by DEC TCP/IP Services. The status codes are described in <reference>(status_table). For synchronous NETLIB calls, these codes are returned in R0 and also in the IOSB, if one is specified; for asynchronous calls, you should always specify an IOSB to receive the status of the network I/O operation. Some NETLIB routines may also return status codes from other facilities, such as the LIB$ and STR$ routines when processing strings. <table>(NETLIB Status Codes\status_table) <table_setup>(2\20) <table_heads>(Symbolic Name\Description) <table_row>(SS$_ABORT\Catch-all code for errors not covered by other codes.) <table_row>(SS$_INSFARG\Not enough arguments specified on NETLIB call.) <table_row>(SS$_BADPARAM\Invalid value specified for an argument to a NETLIB call. This code can also be returned by the underlying TCP/IP driver when an invalid value is specified for a network I/O operation.) <table_row>(SS$_NOSUCHNODE\Destination address required.) <table_row>(SS$_INSFMEM\Memory allocation failure.) <table_row>(SS$_NOPRIV\Insufficient privilege for requested operation.) <table_row>(SS$_ACCVIO\Invalid memory address specified.) <table_row>(SS$_FILALRACC\Socket already connected.) <table_row>(SS$_LINKDISCON\Network link has been disconnected.) <table_row>(SS$_TOOMUCHDATA\Result too large for user's buffer.) <table_row>(SS$_SUSPENDED\I/O operation would block.) <table_row>(SS$_NOTNETDEV\Network operation requested for non-network device.) <table_row>(SS$_PROTOCOL\Protocol type or option incorrect. Protocol or socket type not supported. Other general protocol failure.) <table_row>(SS$_ILLCNTRFUNC\Operation not supported on socket.) <table_row>(SS$_DUPLNAM\Address/port already in use.) <table_row>(SS$_IVADDR\Invalid address.) <table_row>(SS$_UNREACHABLE\Network or host unreachable.) <table_row>(SS$_RESET\Network connection has been reset.) <table_row>(SS$_LINKABORT\Connection aborted by network software.) <table_row>(SS$_CONNECFAIL\Connection failure, or reset by peer process.) <table_row>(SS$_NOLINKS\Socket is not connected.) <table_row>(SS$_SHUT\Socket, host, or network software has been shut down.) <table_row>(SS$_TIMEOUT\Operation timed out.) <table_row>(SS$_REJECT\Connection refused.) <endtable> <ENDAPPENDIX>

(NETLIB_DOC_1) (NETLIB Programmer's Guide) <ABSTRACT>(November, 1994) This manual contains information about NETLIB, a library for TCP/IP network programming on VMS systems. <ENDABSTRACT> <REVISION_INFO>(This is a new manual.) <REVISION_INFO>(Operating System and Version:\VAX/VMS V5.2 or later; OpenVMS AXP V1.0 or later) <REVISION_INFO>(Software Version:\NETLIB V2.0) <ENDTITLE_PAGE>(Matthew Madison<LINE>MadGoat Software) <COPYRIGHT_PAGE> <PRINT_DATE>(01 November 1994) Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. <emphasis>(DISCLAIMER:\bold) The author, the author's employer, and MadGoat Software make no representations or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. AXP, DEC, VAX, VMS, and OpenVMS are trademarks of Digital Equipment Corporation. UNIX is a trademark of Unix System Laboratories, Inc. MultiNet is a trademark of TGV, Inc. TCPware is a trademark of Process Software Corporation. PathWay is a trademark of The Wollongong Group, Inc. <COPYRIGHT_DATE>(1994\MadGoat Software. All Rights Reserved.) <ENDCOPYRIGHT_PAGE> <CONTENTS_FILE> <PREFACE>(\NETLIB_DOC_2) There are several TCP/IP packages available for VMS systems today. Each provides a VMS-style programming interface, using the $QIO system service, and most also provide a <quote>(socket) programming library, based on the communications model developed for BSD UNIX. Unfortunately, there is no standard among all of the packages for the $QIO-based programming interface (most, but not all, emulate Digital's, at least to some degree), and the $QIO-based interface is not very easy to use. The socket libraries provided with these packages provide a somewhat easier-to-use programming interface, but don't permit VMS-style asynchronous programming (using ASTs), and generally require at least a re-LINK, and sometimes source modifications, when moving from one vendor's library to another. NETLIB was originally developed to support MadGoat Software's Message Exchange mail package, which needed to support many TCP/IP packages doing VMS-style asynchronous programming. NETLIB provides a consistent, VMS-style interface for TCP/IP-based network programs, operating with all of the currently available TCP/IP packages available today for VMS (with one minor exception). In addition, NETLIB allows for flexibility in the use of a TCP/IP package, by selecting the vendor-dependent library code at run-time, rather than link-time. <head1>(Intended Audience\NETLIB_INST_3) This manual is intended for programmers writing applications that use NETLIB. <head1>(Document Structure\NETLIB_INST_4) This document consists of an introductory chapter, a section containing routine descriptions, and an appendix describing the status codes returned by NETLIB routines. <head1>(Related Documents\NETLIB_INST_5) The <emphasis>(NETLIB Installation Guide) describes how to install NETLIB. <endpreface> <ENDFRONT_MATTER> <CHAPTER>(Using NETLIB\NETLIB_DOC_3) This chapter discusses the NETLIB programming interface. <HEAD1>(Overview\NETLIB_DOC_4) NETLIB provides a single programming interface that can be used with almost any TCP/IP package for VMS systems. While every package provides a $QIO interface and most also provide a socket library, the advantages to using NETLIB instead are: <list>(unnumbered) <le>NETLIB allows VMS-style asynchronous programming (using ASTs) without having to use the $QIO interface directly. The $QIO programming interface varies from vendor to vendor. <le>NETLIB selects its vendor-specific support code at run-time, allowing you to switch between TCP/IP packages without re-linking your program. You can even have the same application, installed just once, run over different TCP/IP packages at the same time on different nodes in a VMScluster system. <le>NETLIB provides a VMS common language environment style of programming interface, making it easier to use from other languages than a UNIX-type socket library written for C programmers. <endlist> <head2>(NETLIB Services\NETLIB_DOC_5) NETLIB provides services for writing TCP/IP-based network programs, both client and server. Servers can either be standalone, AST-driven programs, or can be single-threaded server processes <quote>(forked) by the <quote>(master server) provided with each TCP/IP package. NETLIB services can be grouped into four basic areas: <list>(unnumbered) <le><emphasis>(Connection services\bold). These routines provide the services necessary for performing TCP/IP network I/O. <le><emphasis>(Line-mode services\bold). These routines provide a line-oriented network reads and writes, for line-oriented protocols that run over TCP. <le><emphasis>(DNS resolver services\bold). These routines provide host name and address lookup services. A direct DNS query routine is also provided. <le><emphasis>(Utility routines\bold). These are routines for doing byte-order conversions, IP address parsing and formatting, and other miscellaneous services. <endlist> <HEAD1>(Header files\NETLIB_DOC_6) NETLIB includes header files for both C and BLISS programming, called NETLIBDEF.H and NETLIBDEF.R32, respectively. The header files reside in the NETLIB_DIR: directory. These files define constants and structures that are used by the NETLIB programming interface. <HEAD1>(NETLIB Data Structures\NETLIB_DOC_7) NETLIB uses several data structures in its programming interface. Some of these data structures (INADDRDEF and SINDEF) are common to all BSD socket-oriented programming libraries, one (MXRRDEF) is special to NETLIB. The header files provided with NETLIB defines these structures for BLISS and C programmers. <HEAD2>(INADDRDEF Structure\NETLIB_DOC_8) The INADDRDEF structure is used for passing an IP address. The contents is (currently) a longword, in network byte order (see <reference>(byte_ordering) for more information). Its definition is (in C) is: <interactive> struct INADDRDEF { unsigned long inaddr_l_addr; } <endinteractive> <HEAD2>(SINDEF Structure\NETLIB_DOC_9) The SINDEF structure defines an IP <quote>(socket,) which is a combination of an IP address and a TCP or UDP port number. Its definition is: <interactive> struct SINDEF { unsigned short sin_w_family; unsigned short sin_w_port; struct INADDRDEF sin_x_addr; unsigned char sin_x_mbz[8]; } <endinteractive> <cp>The <emphasis>(sin_w_family\bold) field should always be set to NETLIB_K_AF_INET (value 2). The <emphasis>(sin_w_mbz\bold) field should always be zeroed. <cp>This is a specific form of the more general SOCKADDRDEF structure for use with IP-based sockets. NETLIB currently only supports IP network programming, so other types of addresses should not be used. <HEAD2>(MXRRDEF Structure\NETLIB_DOC_10) The MXRRDEF structure is used to return MX resource record information in a call to NETLIB_DNS_MX_LOOKUP: <interactive> struct MXRRDEF { unsigned int mxrr_l_preference; unsigned int mxrr_l_length; char mxrr_t_name[128]; } <endinteractive> This structure is NETLIB-specific. <HEAD2>(NETLIB_DNS_HEADER Structure\NETLIB_DOC_11) A domain name server accepts queries and returns replies prefixed with with a standard header. A definition of this header is provided in the NETLIB_DNS_HEADER structure. Refer to the NETLIBDEF header file and the appropriate DNS RFCs (such as RFC 1035) for more information about this header. Only those programs which use the NETLIB_DNS_QUERY routine will need this header definition. <HEAD1>(Byte-Order Considerations\byte_ordering) In NETLIB routines, addresses and port numbers are expected to be in <quote>(network order;) that is, with the high-order byte first. This is opposite the natural byte-order for VAX and AXP systems running VMS, which places the low-order byte first. NETLIB provides routines that can be used to reverse byte order for use in the calls which expect it. <HEAD1>(Synchronous vs. Asynchronous Operation\NETLIB_DOC_12) Most NETLIB routines can be executed synchronously (where the routine uses $QIOW) or asynchronously ($QIO is used instead of $QIOW). To have a routine called asynchronously, specify a non-zero <emphasis>(astadr\bold) argument (and, optionally, the <emphasis>(astprm\bold) argument, to have a parameter passed to the AST routine). <HEAD1>(I/O Status Block\NETLIB_DOC_13) Most NETLIB routines include an optional parameter for a VMS-style I/O status block (IOSB), which is used to return status information to the calling program. The first word of the IOSB is the NETLIB status code for the call; the second word, for read and write operations, is the number of bytes transferred. The second longword of the IOSB is not used by NETLIB. <HEAD1>(Linking NETLIB Programs\NETLIB_DOC_14) To link your program with NETLIB, include the following line in a LINK options file: <interactive> NETLIB_SHRXFR/SHARE <endinteractive> Referencing this logical name will link your program against NETLIB's transfer vector, which at run-time will activate the appropriate vendor-specific version of NETLIB (pointed to by the NETLIB_SHR logical name). <HEAD1>(Contacting the Author\NETLIB_DOC_15) There is no formal support for NETLIB. If you have Internet connectivity, however, you may wish to subscribe to one or more of the following MadGoat Software mailing lists: <list>(simple) <le><emphasis>(Info-MadGoat@wkuvx1.wku.edu\bold) Discussion of MadGoat Software products by users and MadGoat developers. To subscribe, send a message to <emphasis>(Info-MadGoat-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Announce@wkuvx1.wku.edu\bold) Announcements of new releases and new products from MadGoat. To subscribe, send a message to <emphasis>(MadGoat-Announce-Request@wkuvx1.wku.edu) with the word SUBSCRIBE in the first line of the body of the message. <le><emphasis>(MadGoat-Bugs@wkuvx1.wku.edu\bold) Address for reporting bugs in MadGoat Software products. Please include the name of the package and version in the subject header of the message, so the report can be more easily directed to the appropriate developer. <endlist> <part>(Routine Descriptions\rtnpart) <part_page> <title>(<reference>(rtnpart)\<reference>(rtnpart\text)) <abstract> This part describes the each of the NETLIB routines. <endabstract> <endpart_page>(renumber) <routine_section>(NETLIB Routines\RTN) <set_template_heading>(rsdeflist\CONDITION VALUES RETURNED) <comment>(----------------------------------------------------------------) <routine>(NETLIB_ACCEPT\Accept an incoming connection\\NETLIB_DOC_16) <overview> NETLIB_ACCEPT waits for an incoming connection and accepts it, creating a new socket for the new connection. <endoverview> <format> <frtn>(NETLIB_ACCEPT) <fargs>(socket ,newsocket [,remaddr] [,remaddr-size] [,remaddr-len] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket that was established as a listener. <argitem>(newsocket\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Socket for the accepted connection (created and returned by this routine). <argitem>(remaddr\structure\longword (unsigned)\write only\by reference) <argdef>Address of a socket_address structure into which the remote address/port information for the new connection is written. <argitem>(remaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the <emphasis>(remaddr\bold) structure. <argitem>(remaddr-len\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Longword into which the actual returned lenght of the socket address is written. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used as part of a <quote>(passive) open sequence, typically by servers that bind a socket to a specific port number, then establish a listener to handle the incoming connections. This call is used to accept an incoming connection, creating a new socket for the new connection. The listener socket is not affected by this call, so you can call NETLIB_ACCEPT again to wait for another incoming connection on the same port after one accept completes. If you want to know the address and port number of the remote end of the accepted connection, you can either use the <emphasis>(remaddr\bold), <emphasis>(remaddr-size\bold), and <emphasis>(remaddr-len\bold) arguments on this call, or follow this call with a call to NETLIB_GETPEERNAME. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_ADDRESS_TO_NAME\Get the host name for an IP address\\NETLIB_DOC_17) <overview> NETLIB_ADDRESS_TO_NAME performs an inverse host lookup, returning a name associated with an IP address. <endoverview> <format> <frtn>(NETLIB_ADDRESS_TO_NAME) <fargs>(socket, [which], address, addrsize, hostname [,retlen] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket about which you wish to obtain the option information. <argitem>(which\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A code indicating the type of lookup to be performed. Possible values are NETLIB_K_LOOKUP_DNS (1), which requests that the name be looked up using the Domain Name System, and NETLIB_K_LOOKUP_HOST_TABLE (2), which requests that the name be looked up in the local host table. If omitted, the default is NETLIB_K_LOOKUP_DNS. See the Description section for information on package-specific restrictions with this parameter. <argitem>(address\structure\longword (unsigned)\read only\by reference) <argdef>An INADDRDEF structure containing the address to be looked up. <argitem>(addrsize\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The size of the address passed in the <emphasis>(address\bold) parameter. <argitem>(hostname\char_string\character string\write only\by descriptor) <argdef>A buffer into which the returned host name will be written. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The returned length of the host name, in bytes. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine performs an address-to-name lookup on the specified IP address. Each TCP/IP package implements this function slightly differently, so there are some restrictions on the use of this routine. For MultiNet, TCPware, and Pathway, the <emphasis>(which\bold) argument is used to determine whether the lookup should occur using NETLIB's DNS resolver support or using the TCP/IP package's host-table access routines. For these packages, the host-table access method cannot be used at AST level. Also, if a DNS lookup is attempted and the system is not configured for DNS, an SS$_UNSUPPORTED error will be returned. For UCX and CMU TCP/IP, the <emphasis>(which\bold) argument is ignored, since these packages do not provide separate access to DNS and local host tables. For UCX, host table lookup will occur first, followed by a DNS lookup. For CMU, this order is reversed. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_ADDRTOSTR\Format an IP address to a string\\NETLIB_DOC_18) <overview> NETLIB_ADDRTOSTR is a utility routine for formatting an IP address as a character string. <endoverview> <format> <frtn>(NETLIB_ADDRTOSTR) <fargs>(address, string [,retlen]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(address\INADDRDEF structure\longword (unsigned)\read only\by reference) <argdef>An INADDRDEF structure containing the address to be formatted. <argitem>(string\char_string\character string\write only\by descriptor) <argdef>The string to hold the formatted address. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The number of characters written to <emphasis>(string\bold). <endargdeflist> <description> This is a utility routine which formats an IP address to a character string, using the dotted-decimal format. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_BIND\Bind a socket to an address/port\\NETLIB_DOC_19) <overview> NETLIB_BIND sets the address and/or port number for a socket. <endoverview> <format> <frtn>(NETLIB_BIND) <fargs>(socket, socket-address, sockaddr-len [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be bound. <argitem>(socket-address\structure\longword (unsigned)\read only\by reference) <argdef>Socket_address structure describing the addreses and port to which the socket is to be bound. <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used primarily by server programs to bind a socket to a particular port, and is typically followed by a call to NETLIB_LISTEN to open a passive connection on that port. If a program does not bind a socket to a particular local address/port combination, the underlying TCP/IP software will automatically assign an address and/or port. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_CLOSE\Close down a socket\\NETLIB_DOC_20) <overview> NETLIB_CLOSE closes a socket. <endoverview> <format> <frtn>(NETLIB_CLOSE) <fargs>(socket) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be closed. <endargdeflist> <description> This routine deletes the specified socket, closing the associated network communications channel, if one is open. Once closed, the socket can no longer be used; you must open a new one with the NETLIB_SOCKET call. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_CONNECT\Connect a socket to a remote address/port\\NETLIB_DOC_21) <overview> NETLIB_CONNECT connects a socket to a remote address/port. <endoverview> <format> <frtn>(NETLIB_CONNECT) <fargs>(socket, socket-address, sockaddr-len [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be connected. <argitem>(socket-address\structure\longword (unsigned)\read only\by reference) <argdef>Socket_address structure describing the addreses and port to which the socket is to be connected. <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used primarily with TCP-based programs to establish a connection to a remote system. When used with UDP, this routine fixes the address to which subsequent UDP datagrams will be sent. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_CONNECT_BY_NAME\Establish a TCP connection to a host by name\\NETLIB_DOC_22) <overview> NETLIB_CONNECT_BY_NAME establishes a TCP connection to a host using the host's name, rather than its IP address. <endoverview> <format> <frtn>(NETLIB_CONNECT_BY_NAME) <fargs>(socket, hostname, port [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A STREAM-type socket allocated with NETLIB_SOCKET. <argitem>(hostname\char_string\character string\read only\by descriptor) <argdef>A character string containing either a host name or an IP address in dotted-decimal format. <argitem>(port\word_unsigned\word (unsigned)\read only\by reference) <argdef>The port number to connect to on the destination host. Unlike the SIN_W_PORT field of a SINDEF (socket address) structure, this number is specified in <emphasis>(host order), not network order. NETLIB_CONNECT_BY_NAME will automatically convert the port number to network order for you. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine converts the specified name or dotted-decimal address to an IP address and uses NETLIB_CONNECT to connect to the specified host and port. If multiple addresses are returned by the host name lookup, each address will be tried until a connection is established or all addresses have been tried. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_EXPANDNAME\Expand a name in a DNS response\\NETLIB_DOC_23) <overview> NETLIB_DNS_EXPANDNAME is a utility routine used for extracting a domain name from a DNS response. <endoverview> <format> <frtn>(NETLIB_DNS_EXPANDNAME) <fargs>(bufstart, buflen, bufptr, name [,retlen] [,skipcount]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(bufstart\pointer\longword (unsigned)\read only\by value) <argdef>A pointer to the start of the DNS response buffer. <argitem>(buflen\word_unsigned\word (unsigned)\read only\by reference) <argdef>The size of the buffer, in bytes. <argitem>(bufptr\pointer\longword (unsigned)\read only\by value) <argdef>A pointer to the area of the buffer containing the domain name to be expanded. <argitem>(name\char_string\character string\write only\by descriptor) <argdef>A descriptor for a character string buffer into which the expanded name will be written. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The returned length of the expanded name, in bytes. <argitem>(skipcount\word_unsigned\word (unsigned)\write only\by reference) <argdef>The number of bytes in the buffer that were used for the domain name. <endargdeflist> <description> This is a utility routine used when parsing a response returned by a call to NETLIB_DNS_QUERY. It expands a domain name stored in a DNS response out to the typical, human-readable, dotted-domain format. This routine is needed because of the way domain names are represented in DNS responses. Refer to RFC 1035 for further information on the format of DNS queries and responses. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_MX_LOOKUP\Look up MX records for a domain name\\NETLIB_DOC_24) <overview> NETLIB_DNS_MX_LOOKUP looks up a host name, returning any MX records. <endoverview> <format> <frtn>(NETLIB_DNS_MX_LOOKUP) <fargs>(socket, hostname, mxrrlist, mxrrlist-size [,mxrrcount] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Any socket allocated with NETLIB_SOCKET. <argitem>(hostname\char_string\character string\read only\by descriptor) <argdef>The host name to be looked up. <argitem>(mxrrlist\array of structures\longword (unsigned)\write only\by reference) <argdef>An array of MXRRDEF structures into which the MX records will be written. <argitem>(mxrrlist-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The number of elements in the <emphasis>(mxrrlist\bold) array. <argitem>(mxrrcount\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>The actual number of MX records written to <emphasis>(mxrrlist\bold). <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine performs a DNS lookup on the specified name, returning any Mail Exchanger (MX) records for that name. For MultiNet, TCPware, and Pathway, and UCX, this routine is a front-end that uses NETLIB_DNS_QUERY to perform the DNS queries. For CMU TCP/IP, the MX lookups are performed using NAMRES calls. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_QUERY\Perform a DNS query\\NETLIB_DOC_25) <overview> NETLIB_DNS_QUERY formats a domain name service query and returns the response from a DNS server. <endoverview> <format> <frtn>(NETLIB_DNS_QUERY) <fargs>(socket, name, [class], type, buffer, bufsize [,flags] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A socket allocated with NETLIB_SOCKET. Any socket can be used. <argitem>(name\char_string\character string\read only\by descriptor) <argdef>The domain name to be looked up. <argitem>(class\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The class of the query. For Internet domain names, this should be NETLIB_K_DNS_CLASS_IN, which is the default if this parameter is omitted. <argitem>(type\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The type of query. Valid type codes are specified by Internet RFCs on the DNS, the codes provided by NETLIB are listed in <reference>(dns_types). <table>(Domain Name Service query types\dns_types) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_DNS_TYPE_A\1\Address (A) records) <table_row>(NETLIB_K_DNS_TYPE_NS\2\Name Server (NS) records) <table_row>(NETLIB_K_DNS_TYPE_CNAME\5\Canonical Name (CNAME) records) <table_row>(NETLIB_K_DNS_TYPE_SOA\6\Start-of-Authority (SOA) records) <table_row>(NETLIB_K_DNS_TYPE_WKS\11\Well-known-server (WKS) records) <table_row>(NETLIB_K_DNS_TYPE_PTR\12\Pointer (PTR) records) <table_row>(NETLIB_K_DNS_TYPE_HINFO\13\Host information (HINFO) records) <table_row>(NETLIB_K_DNS_TYPE_MX\15\Mail Exchanger (MX) records) <table_row>(NETLIB_K_DNS_TYPE_TXT\16\Text (TXT) records) <table_row>(NETLIB_K_DNS_QTYPE_ALL\255\Any available information) <endtable> <argitem>(buffer\varying_arg\longword (unsigned)\write only\by reference) <argdef>A buffer into which the DNS response will be copied. <argitem>(bufsize\word_unsigned\word (unsigned)\read only\by reference) <argdef>The size of <emphasis>(buffer\bold), in bytes. <argitem>(flags\longword_mask\longword (unsigned)\read only\by reference) <argdef>A bitmask of flags specifying options for this query. Valid flags are listed in <reference>(query_flags). If omitted, the default value for this parameter is 1. <table>(Flag values for NETLIB_DNS_QUERY\query_flags) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_M_DOMAIN_SEARCH\1\Perform a domain search on the default domain.) <table_row>(NETLIB_M_NO_RECURSION\2\Specify a non-recursive query.) <endtable> <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine formats a DNS query and returns the response from any answering name server. If the query fails, an error status is returned. For MultiNet, TCPware, and Pathway, and UCX, the name servers that are queried are those specified for those packages. With MultiNet, for example, the ones listed in the translation string for the logical name for MULTINET_NAMESERVERS are used. For the CMU TCP/IP package, the name servers used by NAMRES are not available to NETLIB, so you must define the logical name NETLIB_NAMESERVERS with the IP address(es) of the name server(s) you want NETLIB to use. If no name servers can be found, SS$_UNSUPPORTED is returned. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_DNS_SKIPNAME\Skip a name in a DNS response\\NETLIB_DOC_26) <overview> NETLIB_DNS_SKIPNAME is a utility routine used for parsing DNS responses which skips over a domain name. <endoverview> <format> <frtn>(NETLIB_DNS_SKIPNAME) <fargs>(bufptr, buflen) <endformat> <returns>(longword_signed\longword (signed)\write only\by value) <argdeflist> <argitem>(bufptr\pointer\longword (unsigned)\read only\by value) <argdef>A pointer to the area of the DNS response buffer that begins the name to be skipped. <argitem>(buflen\word_unsigned\word (unsigned)\read only\by reference) <argdef>A count of the number of bytes in the buffer, starting from <emphasis>(bufptr\bold). <endargdeflist> <description> This is a utility routine used when parsing a response returned by a call to NETLIB_DNS_QUERY. It returns a count of the number of bytes to skip allocated to the domain name positioned in the buffer at location <emphasis>(bufptr\bold). If the operation fails, -1 is returned to indicate an error. This routine is needed because of the way domain names are represented in DNS responses. Refer to RFC 1035 for further information on the format of DNS queries and responses. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_GETPEERNAME\Get remote socket address\\NETLIB_DOC_27) <overview> NETLIB_GETSOCKNAME returns the remote address and port information for a connected socket. <endoverview> <format> <frtn>(NETLIB_GETPEERNAME) <fargs>(socket, socket-address, sockaddr-size, sockaddr-retlen [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket for which the information is to be returned. <argitem>(socket-address\structure\longword (unsigned)\write only\by reference) <argdef>Socket_address structure which will hold the returned address/port information. <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(sockaddr-retlen\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Returned actual length of the socket address. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used to return the remote address and port information for a socket that is connected to a remote system. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_GETSOCKNAME\Get local socket address\\NETLIB_DOC_28) <overview> NETLIB_GETSOCKNAME returns the local address and port information for a socket. <endoverview> <format> <frtn>(NETLIB_GETSOCKNAME) <fargs>(socket, socket-address, sockaddr-size, sockaddr-retlen [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket for which the information is to be returned. <argitem>(socket-address\structure\longword (unsigned)\write only\by reference) <argdef>Socket_address structure which will hold the returned address/port information. <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. <argitem>(sockaddr-retlen\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Returned actual length of the socket address. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used to return the local address and port information for a socket that has been bound or connected. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_GETSOCKOPT\Get socket options\\NETLIB_DOC_29) <overview> NETLIB_GETSOCKOPT gets the current state of a socket option. <endoverview> <format> <frtn>(NETLIB_GETSOCKOPT) <fargs>(socket, level, option, value, valsize [,vallen] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket about which you wish to obtain the option information. <argitem>(level\longword_unsigned\longword (unsigned)\read only\by reference) <argdef><quote>(Level) of the option being set. The only level globally supported is NETLIB_K_LEVEL_SOCKET (value X'FFFF'). Some packages also support protocol-level option settings. <argitem>(option\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Longword representing the option being set. Not all packages support all options, but most support the ones listed in <reference>(option_table). Consult your package-specific documentation on other available options and on option value ranges. The CMU TCP/IP package is not based on sockets, so this call will always return success status with 0 returned length on systems running that package. <argitem>(value\varying_arg\longword (unsigned)\write only\by reference) <argdef>Value to set for the option. Values vary from option to option. <argitem>(valsize\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the <emphasis>(value\bold) argument, in bytes. <argitem>(vallen\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Actual returned length of <emphasis>(value\bold), in bytes. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine provides an interface to the <emphasis>(getsockopt\bold) service provided by most TCP/IP packages (most are based on the BSD socket communications model). Note that not all options are available with all packages, and for the CMU TCP/IP this call is a no-operation -- it will always return a success status, with 0 as the returned length of the option value. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_HTON_LONG\Convert host-order longword to network order\\NETLIB_DOC_30) <overview> NETLIB_HTON_LONG is a utility routine for converting a longword in the local host's byte order to a network-order longword. <endoverview> <format> <frtn>(NETLIB_HTON_LONG) <fargs>(value) <endformat> <returns>(longword_unsigned\longword (unsigned)\write only\by value) <argdeflist> <argitem>(value\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The longword to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a longword to convert it from the native format for the local host (which is <quote>(little-endian) for VAX and AXP systems running VMS) to network order (which is <quote>(big-endian)). The returned value is the network-order longword. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_HTON_WORD\Convert host-order word to network order\\NETLIB_DOC_31) <overview> NETLIB_HTON_WORD is a utility routine for converting a word in the local host's byte order to a network-order word. <endoverview> <format> <frtn>(NETLIB_HTON_WORD) <fargs>(value) <endformat> <returns>(word_unsigned\word (unsigned)\write only\by value) <argdeflist> <argitem>(value\word_unsigned\word (unsigned)\read only\by reference) <argdef>The word to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a word to convert it from the native format for the local host (which is <quote>(little-endian) for VAX and AXP systems running VMS) to network order (which is <quote>(big-endian)). The return value is the network-order word. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_LISTEN\Listen for incoming connections\\NETLIB_DOC_32) <overview> NETLIB_LISTEN sets a socket up to listen for incoming connections. <endoverview> <format> <frtn>(NETLIB_LISTEN) <fargs>(socket [,backlog] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be set up as a listener. <argitem>(backlog\unsigned int\longword (unsigned)\read only\by reference) <argdef>The number of backlogged connections to allow on this listener. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is used as part of a <quote>(passive) open sequence, typically by servers that bind a socket to a specific port number, then establish a listener to handle the incoming connections. This call is usually followed by one or more invocations of NETLIB_ACCEPT to accept the incoming connections. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_NAME_TO_ADDRESS\Get the IP address(es) for a host name\\NETLIB_DOC_33) <overview> NETLIB_NAME_TO_ADDRESS looks up a host name, returning its IP address(es). <endoverview> <format> <frtn>(NETLIB_NAME_TO_ADDRESS) <fargs>(socket, [which], hostname, addrlist, addrlist-size [,addrcount] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket about which you wish to obtain the option information. <argitem>(which\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>A code indicating the type of lookup to be performed. Possible values are NETLIB_K_LOOKUP_DNS (1), which requests that the name be looked up using the Domain Name System, and NETLIB_K_LOOKUP_HOST_TABLE (2), which requests that the name be looked up in the local host table. If omitted, the default is NETLIB_K_LOOKUP_DNS. See the Description section for information on package-specific restrictions with this parameter. <argitem>(hostname\char_string\character string\read only\by descriptor) <argdef>The host name to be looked up. <argitem>(addrlist\array of structures\longword (unsigned)\write only\by reference) <argdef>An array of INADDRDEF structures into which the addresses will be written. <argitem>(addrlist-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The number of elements in the <emphasis>(addrlist\bold) array. <argitem>(addrcount\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>The actual number of addresses written to <emphasis>(addrlist\bold). <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine performs a name-to-address lookup on the specified host name. Each TCP/IP package implements this function slightly differently, so there are some restrictions on the use of this routine. For MultiNet, TCPware, and Pathway, the <emphasis>(which\bold) argument is used to determine whether the lookup should occur using NETLIB's DNS resolver support or using the TCP/IP package's host-table access routines. For these packages, the host-table access method cannot be used at AST level. Also, if a DNS lookup is attempted and the system is not configured for DNS, an SS$_UNSUPPORTED error will be returned. For UCX and CMU TCP/IP, the <emphasis>(which\bold) argument is ignored, since these packages do not provide separate access to DNS and local host tables. For UCX, host table lookup will occur first, followed by a DNS lookup. For CMU, this order is reversed. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_NTOH_LONG\Convert network-order longword to host order\\NETLIB_DOC_34) <overview> NETLIB_NTOH_LONG is a utility routine for converting a longword in the network byte order to a host-order longword. <endoverview> <format> <frtn>(NETLIB_NTOH_LONG) <fargs>(value) <endformat> <returns>(longword_unsigned\longword (unsigned)\write only\by value) <argdeflist> <argitem>(value\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The longword to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a longword to convert it from network order to host order. The return value is the host-order longword. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_NTOH_WORD\Convert network-order word to host order\\NETLIB_DOC_35) <overview> NETLIB_NTOH_WORD is a utility routine for converting a word in the network byte order to a host-order word. <endoverview> <format> <frtn>(NETLIB_NTOH_WORD) <fargs>(value) <endformat> <returns>(word_unsigned\word (unsigned)\write only\by value) <argdeflist> <argitem>(value\word_unsigned\word (unsigned)\read only\by reference) <argdef>The word to be converted. <endargdeflist> <description> This is a utility routine which reverses the byte order of a word to convert it from network order to host order. The return value is the host-order word. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_READ\Receive data from remote system\\NETLIB_DOC_36) <overview> NETLIB_READ reads data sent by a remote system from a socket. <endoverview> <format> <frtn>(NETLIB_READ) <fargs>(socket, buffer [,socket-address] [,sockaddr-size] [,sockaddr-len] [,timeout] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to which data should be written. <argitem>(buffer\unspecified\longword (unsigned)\write only\by descriptor (fixed-length)) <argdef>The address of a descriptor for a buffer to receive the data. <argitem>(socket-address\structure\longword (unsigned)\write only\by reference) <argdef>Socket_address structure to receive the addreses and port from which the data is to be sent. Typically used only with unconnected UDP sockets). <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. Typically used only with unconnected UDP sockets. <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Returned length of the socket address structure. Typically used only with unconnected UDP sockets. <argitem>(timeout\delta_time\quadword (signed)\read only\by reference) <argdef>Amount of time that NETLIB_READ should wait for the read to complete. If omitted, no timeout is used. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine reads data from the socket into the specified buffer. The read will complete when the buffer is full, or if the read times out (if <emphasis>(timeout\bold) is specified). A fixed-length descriptor should be used for the buffer. To obtain the actual number of bytes read in this call, use an I/O status block. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_READLINE\Read a <quote>(line) of data\\NETLIB_DOC_37) <overview> NETLIB_READLINE reads a <quote>(line) of data from the socket. <endoverview> <format> <frtn>(NETLIB_READLINE) <fargs>(socket, buffer [,retlen] [,flags] [,timeout] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket from which data should be read. <argitem>(buffer\char_string\character string\write only\by descriptor) <argdef>The address of a descriptor for the buffer to hold the line. <argitem>(retlen\word_unsigned\word (unsigned)\write only\by reference) <argdef>The address of a word which receives the actual length of the received line. <argitem>(flags\bitmask\longword (unsigned)\read only\by reference) <argdef>The address of a bitmask containing flags controlling this call. Only one flag is currently defined, NETLIB_M_ALLOW_LF (value 1), which causes NETLIB_READLINE to consider either a CR/LF pair or a bare LF as a line terminator. If this argument is omitted, this flag is enabled by default. Otherwise, only a CR/LF pair will be considered a line terminator. <argitem>(timeout\delta_time\quadword (signed)\read only\by reference) <argdef>The address of a VMS delta time value specifying the timeout for this read. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine is intended for TCP-based programs that use a protocol which delimits commands and replies with carriage-return/linefeed pairs. It completes only when the specified buffer is full; when a complete, terminated, line has been received; or if a timeout occurs. The line terminator is stripped from the returned data. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SERVER_SETUP\Socket setup for <quote>(forked) servers\\NETLIB_DOC_38) <overview> NETLIB_SERVER_SETUP creates and sets up the socket used by a server process <quote>(forked) from a TCP/IP package's <quote>(master server). <endoverview> <format> <frtn>(NETLIB_SERVER_SETUP) <fargs>(socket, socket-address, sockaddr-size) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>Returned socket handle for use in subsequent NETLIB calls. <argitem>(socket-address\special_structure\longword (unsigned)\read only\by reference) <argdef>Socket address describing port being opened. See note in description section. <argitem>(sockaddr-size\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the structure passed in <emphasis>(socket-address\bold) argument. <endargdeflist> <description> This routine creates a NETLIB socket for the communications channel in a server program invoked by a TCP/IP package's <quote>(master server.) The <emphasis>(socket-address\bold) and <emphasis>(sockaddr-size\bold) arguments must be provided, although for all packages except CMU TCP/IP they are ignored (the actual address and port number are pre-determined). <NOTE> For at least some TCP/IP packages, this routine should be called <emphasis>(before) any language-specific I/O routines (for example, the <emphasis>(printf\bold) routine in the C run-time library) are called, to prevent the run-time system from interfering with the network channel. <ENDNOTE> <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SETSOCKOPT\Set socket options\\NETLIB_DOC_39) <overview> NETLIB_SETSOCKOPT modifies attributes of a a socket. <endoverview> <format> <frtn>(NETLIB_SETSOCKOPT) <fargs>(socket, level, option, value, vallen [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>The socket you wish to modify. <argitem>(level\longword_unsigned\longword (unsigned)\read only\by reference) <argdef><quote>(Level) of the option being set. The only level globally supported is NETLIB_K_LEVEL_SOCKET (value X'FFFF'). Some packages also support protocol-level option settings. <argitem>(option\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Longword representing the option being set. Not all packages support all options, but most support the ones listed in <reference>(option_table). <table>(Socket options\option_table) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_OPTION_REUSEADDR\4\Allows a port number to be reused. Value is a longword, either 1 (on) or 0 (off). Default for most packages is off, but NETLIB turns this option on automatically unless you explicitly call NETLIB_SETSOCKOPT to set it.) <table_row>(NETLIB_K_OPTION_SNDBUF\4097\Sets socket buffer size for sends. Value is a longword, typically with a maximum value of 32768.) <table_row>(NETLIB_K_OPTION_RCVBUF\4098\Sets socket buffer size for receives. Value is a longword, typically with a maximum value of 32768.) <endtable> Consult your package-specific documentation on other available options and on option value ranges. The CMU TCP/IP package is not based on sockets, so this call has no effect on systems running that package. <argitem>(value\varying_arg\longword (unsigned)\read only\by reference) <argdef>Value to set for the option. Values vary from option to option. <argitem>(vallen\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the <emphasis>(value\bold) argument, in bytes. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine provides an interface to the <emphasis>(setsockopt\bold) service provided by most TCP/IP packages (most are based on the BSD socket communications model). Note that not all options are available with all packages, and for the CMU TCP/IP this call is a no-operation. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SHUTDOWN\Shut down a connection\\NETLIB_DOC_40) <overview> NETLIB_SHUTDOWN shuts down a connection without deleting the socket. <endoverview> <format> <frtn>(NETLIB_SHUTDOWN) <fargs>(socket [,shuttype] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to be set up as a listener. <argitem>(shuttype\unsigned int\longword (unsigned)\read only\by reference) <argdef>Type of shutdown to be performed. Possible values are listed in <reference>(shut_table). If omitted, the default is NETLIB_K_SHUTDOWN_RECEIVER. <table>(Shutdown types\shut_table) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_SHUTDOWN_RECEIVER\0\Prevent any further receives.) <table_row>(NETLIB_K_SHUTDOWN_SENDER\1\Prevent any further sends.) <table_row>(NETLIB_K_SHUTDOWN_BOTH\2\Prevent any further sends/receives.) <endtable> This parameter has no meaning when using the CMU TCP/IP package. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine closes the network connection currently open on the specified socket, without deleting the socket. Any data still waiting to be received or sent can be discarded or retained by specifying an appropriate shutdown type in <emphasis>(shuttype\bold). For the CMU TCP/IP package, the shutdown type is not used; the CMU close operation does not provide this option. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_SOCKET\Create a NETLIB communication endpoint\\NETLIB_DOC_41) <overview> NETLIB_SOCKET creates a <quote>(socket) -- that is, a local endpoint for TCP/IP communication. <endoverview> <format> <frtn>(NETLIB_SOCKET) <fargs>(socket [,socket-type] [,socket-family]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\write only\by reference) <argdef>The returned socket context, for use in subsequent NETLIB calls. <argitem>(socket-type\longword_unsigned \longword (unsigned)\read only\by referencee) <argdef>Type of socket to be created. Allowed values are shown in <reference>(socket_type_table). If omitted, the default is NETLIB_K_TYPE_STREAM. <table>(Socket types\socket_type_table) <table_setup>(3\25\5) <table_heads>(Symbolic name\Value\Description) <table_row>(NETLIB_K_TYPE_STREAM\1\Connection-oriented socket (for TCP).) <table_row>(NETLIB_K_TYPE_DGRAM\2\Connectionless socket (for UDP).) <endtable> <argitem>(socket-family\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Address/protocol family. Only NETLIB_K_AF_INET (value 2) is permitted, and is assumed by default if omitted. <endargdeflist> <description> This routine creates a <quote>(socket) (an endpoint for network communication). One socket is required for each network connection. This will be the first call in most NETLIB-based programs. The only exception to this rule is a program that is intended to be run as a <quote>(forked) server from a TCP/IP package's <quote>(master server), which will use the NETLIB_SERVER_SETUP routine instead. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_STRTOADDR\Convert a dotted-address to binary form\\NETLIB_DOC_42) <overview> NETLIB_STRTOADDR is a utility routine for converting a character string holding a dotted-decimal IP addreses into its binary equivalent. <endoverview> <format> <frtn>(NETLIB_STRTOADDR) <fargs>(string, address) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(string\char_string\character string\read only\by descriptor) <argdef>The string containing the dotted-decimal address. <argitem>(address\INADDRDEF structure\longword (unsigned)\write only\by reference) <argdef>An INADDRDEF structure to hold the returned address. <endargdeflist> <description> This is a utility routine which parses a character string containing an IP address in dotted-decimal format, returning the binary representation of that address in network order (suitable for a call to NETLIB_CONNECT, for example). <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_WRITE\Send data to remote system\\NETLIB_DOC_43) <overview> NETLIB_WRITE writes data to a socket for transmission to a remote system. <endoverview> <format> <frtn>(NETLIB_WRITE) <fargs>(socket, buffer [,socket-address] [,sockaddr-len] [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to which data should be written. <argitem>(buffer\unspecified\longword (unsigned)\read only\by descriptor) <argdef>The address of a descriptor for the data to be sent. <argitem>(socket-address\structure\longword (unsigned)\read only\by reference) <argdef>Socket_address structure describing the addreses and port to which the data is to be sent. Used only with unconnected UDP sockets). <argitem>(sockaddr-len\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Size of the socket address structure. Used only with unconnected UDP sockets. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine writes the specified data to the socket for transmission to the remote system. For UDP sockets that have not been connected to a specific remote address, the <emphasis>(socket-address\bold) argument specifies the remote address/port to which the datagram is to be sent. <enddescription> <comment>(----------------------------------------------------------------) <routine>(NETLIB_WRITELINE\Send data with CR/LF termination\\NETLIB_DOC_44) <overview> NETLIB_WRITELINE writes data to a socket for transmission to a remote system, terminating the data with a CR/LF pair. <endoverview> <format> <frtn>(NETLIB_WRITELINE) <fargs>(socket, buffer [,iosb] [,astadr] [,astprm]) <endformat> <returns>(cond_value\longword (unsigned)\write only\by value) <argdeflist> <argitem>(socket\longword_unsigned\longword (unsigned)\read only\by reference) <argdef>Socket to which data should be written. <argitem>(buffer\char_string\character string\read only\by descriptor) <argdef>The address of a descriptor for the data to be sent. <argitem>(iosb\io_status_block\longword (unsigned)\write only\by reference) <argdef>I/O status block to receive the status for this call. <argitem>(astadr\procedure\longword (unsigned)\call\by reference) <argdef>Address of an AST routine to be invoked on completion of this operation. <argitem>(astprm\user_arg\longword (unsigned)\read only\by value) <argdef>Parameter to be passed to the AST routine. <endargdeflist> <description> This routine functions identically to NETLIB_WRITE, but adds a carriage-return/ linefeed pair to the data sent to the remote system. It is intended for TCP-based programs that use a protocol which delimits commands and responses with CR/LFs. <enddescription> <endroutine_section> <APPENDIX>(Status Codes\status_codes) NETLIB translates all TCP/IP status codes into the codes used by DEC TCP/IP Services. The status codes are described in <reference>(status_table). For synchronous NETLIB calls, these codes are returned in R0 and also in the IOSB, if one is specified; for asynchronous calls, you should always specify an IOSB to receive the status of the network I/O operation. Some NETLIB routines may also return status codes from other facilities, such as the LIB$ and STR$ routines when processing strings. <table>(NETLIB Status Codes\status_table) <table_setup>(2\20) <table_heads>(Symbolic Name\Description) <table_row>(SS$_ABORT\Catch-all code for errors not covered by other codes.) <table_row>(SS$_INSFARG\Not enough arguments specified on NETLIB call.) <table_row>(SS$_BADPARAM\Invalid value specified for an argument to a NETLIB call. This code can also be returned by the underlying TCP/IP driver when an invalid value is specified for a network I/O operation.) <table_row>(SS$_NOSUCHNODE\Destination address required.) <table_row>(SS$_INSFMEM\Memory allocation failure.) <table_row>(SS$_NOPRIV\Insufficient privilege for requested operation.) <table_row>(SS$_ACCVIO\Invalid memory address specified.) <table_row>(SS$_FILALRACC\Socket already connected.) <table_row>(SS$_LINKDISCON\Network link has been disconnected.) <table_row>(SS$_TOOMUCHDATA\Result too large for user's buffer.) <table_row>(SS$_SUSPENDED\I/O operation would block.) <table_row>(SS$_NOTNETDEV\Network operation requested for non-network device.) <table_row>(SS$_PROTOCOL\Protocol type or option incorrect. Protocol or socket type not supported. Other general protocol failure.) <table_row>(SS$_ILLCNTRFUNC\Operation not supported on socket.) <table_row>(SS$_DUPLNAM\Address/port already in use.) <table_row>(SS$_IVADDR\Invalid address.) <table_row>(SS$_UNREACHABLE\Network or host unreachable.) <table_row>(SS$_RESET\Network connection has been reset.) <table_row>(SS$_LINKABORT\Connection aborted by network software.) <table_row>(SS$_CONNECFAIL\Connection failure, or reset by peer process.) <table_row>(SS$_NOLINKS\Socket is not connected.) <table_row>(SS$_SHUT\Socket, host, or network software has been shut down.) <table_row>(SS$_TIMEOUT\Operation timed out.) <table_row>(SS$_REJECT\Connection refused.) <endtable> <ENDAPPENDIX>