1 TCPIP_Services TCP/IP is an open communications standard that enables any connected host to communicate with any other connected host. The TCP/IP Services software is the HP OpenVMS implementation of industry-standard TCP/IP networking protocols. The TCP/IP Services software allows you to communicate and share resources with remote OpenVMS systems, UNIX systems, and other systems that support the TCP/IP protocol suite. 2 Product_Overview The product consists of a number of components that implement various TCP/IP protocols. These components provide remote computing, file transfer, resource sharing, electronic mail, and network services as follows: Remote Computing FINGER Display information about users logged in to a remote host, such as their login user names or programs they are using. RCP Copy files between the local host and a remote host or between two remote hosts. Requests are authenticated on the remote host or hosts using the user name supplied by RCP. RLOGIN Connect to a remote host, which starts an interactive login session. Requests are authenticated on the remote host using the user name supplied by RLOGIN. RMT/RCD Access magnetic tape and CD drives on a remote host as though they are available locally. RSH Connect to a remote host, which executes the command you specify. Requests are authenticated on the remote host using the user name supplied to RSH. RSH/PASSWORUse the REXEC facility to connect to the remote host, which executes the command you specify. Requests are authenticated on the remote host using the user name and password supplied by RSH. RMT/RCD Access magnetic tape and CD drives on a remote host as though they are available locally. TELNET Log in to a remote host in a network using various options to customize the session, control output from the remote host, and negotiate compatibility differences. To start a TELNET session, enter the following command: $ TELNET File Transfer FTP Create, delete, and copy files and directories between hosts. To start an FTP session, enter the following command: $ FTP TFTP Transfer files using the UDP protocol and no authentication. Typically used during the bootstrap process of diskless systems. Resource Sharing LPD/LPR Print files on remote and local hosts. NFS Authenticate requests and provide access to remote files. TELNETSYM Print files on remote hosts using the TELNET protocol. Electronic Mail IMAP View, move, copy, and delete electronic mail from your PC, and in conjunction with SMTP, create and send mail. POP Send and receive electronic mail from your PC. SMTP Send and receive electronic mail from remote hosts. Programming Utilities MIBCOMP Compile SNMP subagent source files in ASN.1 format. RPCGEN Create programming skeletons that implement the RPC mechanism. Network Services BIND Name and address resolution service to distribute and manage host information. BOOTP Answer bootstrap requests from remote devices. DHCP Configure and maintain your IP address space including the temporary assignment of IP addresses. Management Manage your TCP/IP environment. To start the commands management control program, enter the following command: $ TCPIP For online descriptions of the management commands, enter the following command: $ TCPIP HELP NSLOOKUP Determine if your local name server is running correctly or retrieve information from remote servers. NTP Synchronize time between hosts. PPP Connect a node to a network using IP or other supported network protocols. SLIP, Connect a node to a network over a serial connection CSLIP using IP. SNMP Monitor and manage network devices from across an internetwork. TCPDUMP Analyze dumps and capture packets. TCPTRACE Trace packets going in and out of the system. 2 BIND The Domain Name Service (DNS) is an Internet service that maintains and distributes information about Internet hosts. DNS consists of several databases that store host names and host IP addresses. With DNS, there is no central storage of data - no one server knows everything about all the Internet domains. In UNIX environments, DNS is implemented by the Berkeley Internet Name Domain (BIND) software. HP TCP/IP Services for OpenVMS implements a BIND server based on the Internet Software Consortium's (ISC) BIND 8.1.2. The BIND 8.1.2 implementation provides new configuration options and a new format for configuring the BIND name server. In addition to standard BIND features, the TCP/IP Services product provides cluster load balancing and round-robin scheduling. Configuring and managing BIND on your OpenVMS host involves the following tasks: o Configuring the BIND resolver and name server using TCPIP$CONFIG o Modifying the BIND configuration using SET CONFIGURATION commands or by editing the BIND 8 configuration file o Setting up name servers to be the following: primary (master), secondary (slave), cache-only, and forwarder o Populating the BIND server databases o Displaying name server information o Using NSLOOKUP to query a name server 2 BOOTP The Bootstrap Protocol (BOOTP) server answers network bootstrap requests from diskless workstations and other network devices such as routers, terminal servers, and network switching equipment. When the BOOTP server receives such a request, it looks up the workstation's address in the BOOTP database file. The Trivial File Transfer Protocol (TFTP) handles the file transfer from a BOOTP server to a diskless client or other remote system. The client initiates the file transfer. Configuring and managing BOOTP on your OpenVMS host involves the following tasks: o Planning your BOOTP configuration o Configuring the BOOTP and TFTP components using TCPIP$CONFIG o Modifying the BOOTP configuration using logical names and management commands o Creating a BOOTP database o Monitoring the BOOTP and TFTP processes 2 DHCP Dynamic Host Configuration Protocol (DHCP), a superset of the Bootstrap Protocol (BOOTP), provides a centralized approach to the configuration and maintenance of IP address space. It allows the system manager to configure various clients on the network from a single location. DHCP allocates temporary or permanent IP addresses from an address pool to client hosts on the network. DHCP can also configure client parameters such as default gateway parameters, domain name server parameters, and subnet masks for each host running a DHCP client. Configuring and managing the DHCP server requires the following tasks: o Configuring the server using TCPIP$CONFIG o Setting up the NETMASKS file o Defining a set of IP addresses as static, dynamic, or finite o Specifying lease time o Configuring default gateways and DNS domain names o Using utility commands to modify DHCP databases 2 TFTP The Trivial File Transfer Protocol (TFTP) transfers files from a BOOTP server to diskless clients or other remote systems. The client initiates the file transfer. When the client receives the configuration information in the BOOTP response, it sends a request to the TFTP server host named in the response. This request is necessary only if the client must retrieve the load file. If the client sends a read request (RRQ) to the TFTP server, the server attempts to locate the file. Configuring and managing TFTP on your OpenVMS host involves the following tasks: o Configuring the TFTP and BOOTP components using TCPIP$CONFIG o Monitoring the TFTP and BOOTP processes o Using management commands to enable and disable TFTP and to configure TFTP in the service database 2 NTP The Network Time Protocol (NTP) provides a means to synchronize time and coordinate time distribution throughout a TCP/IP network. NTP aims to provide accurate and dependable timekeeping for hosts on TCP/IP networks. NTP provides synchronization traceable to clocks of high absolute accuracy and avoids synchronization to clocks keeping incorrect time. Configuring and managing NTP on your OpenVMS host involves the following tasks: o Determining which network hosts to use for synchronization o Creating and populating the NTP configuration file with the list of participating hosts o Defining a time-zone differential (offset) logical name o Using the NTPDATE program to set the local date and time o Using the NTPTRACE utility to determine the source from which an NTP server obtains its time o Using the NTPDC query program to make runtime changes to NTP 2 SNMP The Simple Network Management Protocol (SNMP) is network management technology that facilitates the management of a TCP/IP network or internet in a vendor-independent manner. SNMP enables a network administrator to manage the various network components using a set of well-known procedures understood by all components, regardless of the vendor that manufactured them. Configuring the SNMP agent on your OpenVMS system allows a remote SNMP management client to obtain information about your host and to set optional network parameters. Configuring and managing SNMP on your OpenVMS host involves the following tasks: o Configuring the SNMP component using TCPIP$CONFIG o Modifying the SNMP configuration using the SET CONFIGURATION SNMP command and qualifiers o Modifying master agent and subagent behavior by defining logical names o Testing the master agent and subagent behavior using the MIB browser program, the trap sender program, and the trap receiver program o Writing your own subagent, as appropriate for your network 2 NFS The Network File System (NFS) protocols enable internet clients to access remote files that reside on NFS servers. The TCP/IP Services implementation of the Network File System (NFS) includes the following software: o NFS server o NFS client o NFS file system o PC-NFS print services 3 Server The NFS server software lets you set up file systems on your local system for export to users on remote NFS client hosts. These files and directories, even though they physically reside on the local system, appear to the remote user to be on the remote host. Configuring and managing the NFS server on your OpenVMS host involves the following tasks: o Configuring the NFS server using TCPIP$CONFIG o Configuring the PC-NFS daemon using TCPIP$CONFIG (if you plan to export file systems to PC-NFS client hosts) o Modifying NFS and PC-NFS configuration using management commands o Selecting a file system: OpenVMS or container (UNIX style) o Modifying server and container file system characteristics by defining logical names o Registering users and hosts in the proxy database file o Backing up the file system o Setting up and exporting the file system o Maintaining and examining a container file system o Setting up NFS security features o Improving NFS server performance 3 Client The NFS client software enables client users to access file systems made available by an NFS server. These files and directories physically reside on the remote (server) host but appear to the client as if they were on the local system. For example, any files accessed by an OpenVMS client - even a UNIX file - appear to be OpenVMS files and have typical OpenVMS file names. Configuring and managing the NFS client on your OpenVMS host involves the following tasks: o Configuring the NFS client using TCPIP$CONFIG o Registering users in the proxy database o Mounting (attaching) remote files and directories exported by the NFS server 3 File_System The NFS file system on OpenVMS includes a hierarchy of devices, directories, and files stored on a File-11 On-Disk Structure (ODS-2) formatted disk. You can set up and export two different kinds of file systems: o Traditional OpenVMS file system o UNIX (container) file system built on top of an OpenVMS file system. To set up and maintain these file systems, you issue management commands. 3 PC-NFS The TCP/IP Services implementation of PC-NFS provides the following print services to personal computers (PCs) running NFS Client software: o Authentication A PC that wants to request access to an NFS Server must first get its user identification / group identification (UID/GID) pair from a remote authentication server running TCP/IP Services. o Printing You set up the PC-NFS daemon software using TCPIP$CONFIG, and you manage the software by issuing management commands. 2 SLIP_and_PPP TCP/IP Services supports serial connections using the following protocols: o Serial Line IP (SLIP) and Compressed SLIP (CSLIP) protocols Sends datagrams across the serial line as a series of bytes, using special characters to mark when a series of bytes should be grouped together o Point-to-Point Protocol (PPP) (Alpha only) Uses a frame format that includes a field to identify the protocol (for example: IP or OSI). One of the largest applications for SLIP and PPP is dialup access. With PPP, you can establish a dynamic IP network connection over a serial line without the extensive use of additional router or server hardware. PPP ensures interoperability between systems from a wide variety of vendors. Because SLIP has been in use for a longer period of time, it is available for most terminal servers and in most PC implementations of TCP/IP. CSLIP provides header compression to improve packet throughput, which is especially beneficial for small packets. For either SLIP or PPP connections, a host can function as a dialup provider (server) to respond to incoming connection requests. Or, a host can function as a client dialing in to a dialup provider. Setting up your OpenVMS host as a dialup provider or client involves the following tasks: o Installing the appropriate virtual terminal driver o Configuring the interface for serial line connections (optional for clients) o Configuring your modem o Setting up an asynchronous port for modem connections o Enabling IP forwarding and dynamic routing (dialup provider only) o Initiating a connection (client only) 2 Management_Tools TCP/IP Services includes the following network management tools: o A management control program with a command-line interface, event logging, and error and information messages o UNIX commands o The configuration procedure TCPIP$CONFIG o The DHCP graphical user interface (GUI) o The TCPTRACE utility o Logical names o Startup and shutdown procedures o The NSLOOKUP utility o SNMP and the Extensible SNMP (eSNMP) 2 UNIX_Commands UNIX management commands are available for system managers experienced in managing a UNIX network subsystem. The following table introduces these commands. Command Description arp Controls and displays ARP tables for the specified host. ifconfig Configures or displays network interface parameters, redefines an address for a particular interface, or sets options such as an alias list, broadcast address, or access filter. netstat Displays network statistics of sockets, data link counter aliases, network interfaces, and a host's routing table. nfsstat Displays statistical information about the network file system (NFS) and remote procedural call (RPC) interfaces in the kernel. It can also be used to reinitialize this information. ripquery Requests all routes known by a RIP gateway by sending a RIP request or a POLL command. route Allows you to manipulate the routing table manually. Normally, a system routing table management component, such as GATED or ROUTED, will tend to this task. sysconfig Manages and displays the network attributes in the kernel subsystem configuration. sysconfigdb Manages and displays network attributes in the subsystem configuration table (TCPIP$ETC:SYSCONFIGTAB.DAT). traceroute Displays the route that packets take to a network host. whois Displays user, host, and organization names in the Network Information Center (NIC) database. For more information, see the help available at the TCPIP> prompt. For example, to display ifconfig flags and parameters, enter the following: TCPIP> HELP ifconfig 2 Routing Routing allows traffic from your local network to reach its destination elsewhere on the internet. All hosts and gateways on a network use routing protocols to exchange and store routing information. Routing is simply the act of forwarding datagrams based on information stored in a routing table. The TCP/IP Services product provides two types of routing: o Static Because static routing requires manual configuration, it is most useful when the number of gateways is limited and where routes do not change frequently. o Dynamic Dynamic routing tables use information received by means of routing protocol updates; when routes change, the routing protocol provides information on the changes. Routing daemons implement a routing policy, that is, the set of rules that decide which routes go in to the routing table. A routing daemon writes routing messages to a routing socket causing the kernel to add a new route, delete an existing route, or modify an existing route. The kernel also generates routing messages that can be read by any routing socket when events occur that might be of interest to the process; for example, when the interface has gone down or a redirect has been received. TCP/IP Services implements two routing daemons: the Routing Daemon (ROUTED) and the Gateway Routing Daemon (GATED). 3 ROUTED ROUTED supports the Routing Information Protocol (RIP). Use TCPIP$CONFIG to enable ROUTED. 3 GATED GATED supports interior and exterior gateway protocols. It obtains information from several routing protocols and selects the best routes based on that information. Before enabling GATED, you must configure the GATED protocols by editing the file TCPIP$GATED.CONF. Use TCPIP$CONFIG to enable dynamic routing. 4 GATED_Protocols You can configure GATED to use one or more of the following protocols: Protocol RFC Description Routing Information RFC RIP is a commonly used interior Protocol (RIP) 1058, protocol that selects the route Versions 1 and 2 RFC 1723 with the lowest metric (hop count) as the best route. Open Shortest Path RFC 1583 Another interior routing First (OSPF) Version protocol, OSPF is a link-state 2 protocol (shortest path first) and better suited than RIP foruse in complex networks with many routers. Exterior Gateway RFC 904 EGP exchanges reachability Protocol (EGP) information between autonomous systems. An autonomous system is usually defined as a set of routers under a single administration, using an interior gateway protocol and common metric to route packets. Autonomous systems use exterior routing protocols to route packets to other autonomous systems. Border Gateway RFCs Like EGP, BGP exchanges Protocol (BGP) 1163, reachability information 1267, between autonomous systems 1771 but supports nonhierarchical topologies. BGP uses path attributes to provide more information about each route. Path attributes can include, for example, administrative preferences based on political, organizational, or security considerations. Router Discovery RFC 1256 This protocol is used to inform hosts of the availability of hosts it can send packets to and to supplement a statically configured default router. 2 Command_Syntax Use the following rules when you type a command line: o OpenVMS and UNIX command syntax Most command descriptions specify both a DCL syntax and a UNIX syntax. You can, therefore, use command lines in either syntax. For example, the following two command lines achieve the same results: TELNET> CONNECT BENTLEY TELNET> open bentley o Keyword abbreviations You can abbreviate commands and qualifiers to the fewest number of characters, usually three, that uniquely identifies the keyword. For example, the following two command lines achieve the same results: $ RL RENT /USE=BUNNINGS $ RLOGIN RENT /USER_NAME=BUNNINGS o Quotation marks Due to differences in OpenVMS and UNIX command syntax, some commands require quotation marks for selected keywords. These requirements apply to case sensitivity, slashes, and certain special characters (such as &, =, and \). UNIX is case sensitive; UNIX host names, user names, and passwords are usually lowercase. Enclosing them in quotation marks preserves the correct casing. Refer to each individual component for its specific command syntax. o Names and addresses Unless otherwise stated, whenever you specify a host on a command line, you can use its host name, a fully qualified domain name, or its IP address. The following examples show two ways to enter the TELNET command to connect to host VENDOR at IP address 17.22.3.4. $ TELNET VENDOR Trying...17.22.3.4 Connected to VENDOR. Escape character is '^]'. () UNIX V5 (vendor.goods.igcorp.com) login: or $ TELNET 17.22.3.4 Trying...17.22.3.4 Connected to 17.22.3.4. Escape character is '^]'. () UNIX V5 (vendor.goods.igcorp.com) login: o File and directory names When you specify OpenVMS directory names and file names, follow OpenVMS file specification rules, as explained in the OpenVMS documentation. Likewise, when you specify UNIX directory names and file names, follow UNIX file specification rules, as explained in the documentation supplied with the UNIX system. o Multiple values for parameters To specify multiple values for command parameters, such as host names and directories, follow these guidelines: - Separate elements with commas. - Wildcards are valid. - A space between multiple elements is optional. The following FTP GET command copies the files PROJ1.TXT and GROUP1.TXT, using a comma to separate the file names in the command line: FTP> GET PROJ1.TXT, GROUP1.TXT The following FTP GET command uses the asterisk (*) wildcard to copy all files starting with the letters "PROJ1": FTP> GET PROJ1*.* o Multiple values for qualifiers To specify multiple values for qualifiers, enclose them in parentheses as follows: /qualifier=(value1,value2, value3) For example, the following LPRM command deletes three jobs from a remote print queue: $ LPRM EST_4_1997_Q /ENTRY=(555,556,558) o Numeric values Unless stated otherwise, all values are decimal. o Braces and brackets Command format descriptions include braces and brackets. You should understand the meaning of the braces and brackets: - Braces ( { } ) - Indicate that you must specify at least one of the enclosed values. Each element is either listed on a separate line or separated by vertical bars (|). Occasionally, you may need to specify all of the enclosed values (this case is always noted). Example: The command SET MODE requires you to specify either CHAR or LINE. SET MODE {CHAR}| {LINE} - Brackets ( [ ] ) - Indicate that the enclosed values are optional. Example 1: The last two parameters for the TELNET CONNECT command are enclosed in brackets, which means they are optional. In this example, the port can be specified without a terminal type, and the host without a port. CONNECT host [ port [terminal_type ] ] Example 2: The format of the RSH command shows that all the qualifiers and the remote_command parameter are optional. RSH host [ /EIGHTBIT ] [ /ESCAPE_CHARACTER=character ] [ /LOG_FILE=file ] [ /[NO]LOWERCASE ] [ /PASSWORD=password ] [ /[NO]SYSERROR ] [ /TERMINAL_SPEED=n ] [ /TERMINAL_TYPE=type ] [ /[NO]TRUNCATE_USER_NAME ] [ /USER_NAME=remote_user_name ] [ remote_command ] 2 NSLOOKUP NSLOOKUP is a debugging tool provided with BIND that allows anyone to directly query a name server and retrieve information. Use NSLOOKUP to determine if your local name server is running correctly or for retrieving information from remote servers. NSLOOKUP makes direct queries to name servers around the world to obtain DNS information, including: o Host names and addresses on the local domain o Host names and addresses on remote domains o Host names that serve as mail exchangers (MX records) o Name servers for a specific zone NOTE The NSLOOKUP utility is deprecated. HP recommends that you use the dig utility instead. For more information, see the HP TCP/IP Services for OpenVMS Management guide. 2 Tracing The TCPTRACE utility lets you trace packet flow between the local host and remote hosts. You can either monitor all packet flow or use the various qualifiers to monitor only those packets of interest. 3 Starting To start the TCPTRACE utility use the TCPTRACE command: $ TCPTRACE HOST1 /FULL /PACKETS=30 3 Stopping To stop the TCPTRACE utility use CTRL/C. 2 Programming_Interfaces TCP/IP Services includes a standard C sockets API and a standard Open Network Computing Remote Procedure Call (ONC RPC) API. The standard C socket API provides UNIX-style access to the TCP and UDP transports and to the IP network layer. The ONC RPC library provides a method of creating communicating programs without the need to program the details of the transport protocol being used. The ONC RPC library is divided into calls frequently used by client programs, calls used to access the Portmapper utility, and calls frequently used by server programs. The ONC RPC library also includes XDR routines which provide the ability to transport data over the network in a standard fashion. 3 RPC_Client_Routines Client routines allow C programs to make procedure calls to server programs across the network. Important: In order to maintain uniqueness for the OpenVMS HELP utility, some client routines have a "_#" appended at the end. Do not use the "_#" when coding the routine in a program. 4 auth_destroy A macro that frees the memory associated with the authentication handle created by the authnone_create and authunix_create routines. Format #include void auth_destroy(AUTH *auth_handle) 5 Arguments auth_handle An RPC authentication handle created by the authnone_create, authunix_create, or authunix_create_default routine. 5 Description Frees the memory associated with the AUTH data structure created by the authnone_create, authunix_create, or authunix_create_ default routine. Be careful not to reference the data structure after calling this routine. 5 Return_Values None 4 authnone_create Creates an authentication handle for passing null credentials and verifiers to remote systems. Format #include AUTH *authnone_create ( ) 5 Arguments None 5 Description Creates and returns an authentication handle that passes null authentication information with each remote procedure call. Use this routine if the server process does not require authentication information. RPC uses this routine as the default authentication routine unless you create another authentication handle using either the authunix_create or authunix_create_ default routine. 5 Return_Values AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed. 4 authunix_create Creates and returns an RPC authentication handle that contains UNIX-style authentication information. Format #include AUTH *authunix_create(char *host, int uid, int gid, int len, int *aup_gids ); 5 Arguments host Pointer to the name of the host on which the information was created. This is usually the name of the system running the client process. uid The user's user identification. gid The user's current group. len The number of elements in aup_gids array. NOTE This parameter is ignored by the product's RPC implementation. aup_gids A pointer to an array of groups to which the user belongs. NOTE This parameter is ignored by the product's RPC implementation. 5 Description Implements UNIX-style authentication parameters. The client uses no encryption for its credentials and only sends null verifiers. The server sends back null verifiers or, optionally, a verifier that suggests a new shorthand for the credentials. 5 Return_Values AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed. 4 authunix_create_default Returns a default authentication handle. Format #include AUTH *authunix_create_default( ) 5 Arguments None 5 Description Calls the authunix_create routine with the local host name, effective process ID and group ID, and the process default groups. 5 Return_Values AUTH * Authentication handle containing the pertinent information. NULL Indicates allocation of AUTH handle failed. 5 Examples 1.auth_destroy(client->cl_auth) client->cl_auth = authunix_create_default(); This example overrides the default authnone_create action. The client handle, client, is returned by the clnt_create, clnt_ create_vers, clnttcp_create, or clntudp_create routine. 4 callrpc Executes a remote procedure call. Format #include int callrpc(char *host, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out); 5 Arguments host A pointer to the name of the host on which the remote procedure resides. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. in A pointer to the remote procedure's arguments. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. 5 Description Calls the remote procedure associated with prognum, versnum, and procnum on the host host. This routine performs the same functions as a set of calls to the clnt_create, clnt_call, and clnt_destroy routines. This routine returns RPC_SUCCESS if it succeeds, or the value of enum clnt_stat cast to an integer if it fails. The routine clnt_perrno is handy for translating a failure status into a message. NOTE Calling remote procedures with this routine uses UDP/IP as a transport; see clntudp_create for restrictions. You do not have control of timeouts or authentication using this routine. If you want to use the TCP transport, use the clnt_ create or clnttcp_create routine. 5 Return_Values RPC_SUCCESS Indicates success. clnt_stat Returns a value of type enum clnt_stat cast to type int containing the status of the callrpc operation. 4 clnt_broadcast Executes a remote procedure call that is sent to all locally connected networks using the broadcast address. Format #include enum clnt_stat clnt_broadcast(u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char * in, xdrproc_t outproc, char * out, resultproc_t eachresult); 5 Arguments prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. in A pointer to the remote procedure's arguments. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. eachresult Called each time the routine receives a response. Specify the routine as follows: int eachresult(char *resultsp, struct sockaddr_in *addr) resultsp is the same as the parameter passed to clnt_broadcast(), except that the remote procedure's output is decoded there. addr is a pointer to a sockaddr_in structure containing the address of the host that sent the results. If eachresult is NULL, the clnt_broadcast routine returns without waiting for any replies. 5 Description Performs the same function as the callrpc routine, except that the call message is sent to all locally connected networks using the broadcast address. Each time it receives a response, this routine calls the eachresult routine. If eachresult returns zero, clnt_broadcast waits for more replies; otherwise it assumes success and returns RPC_SUCCESS. NOTE This routine uses the UDP protocol. Broadcast sockets are limited in size to the maximum transfer unit of the data link. For Ethernet, this value is 1400 bytes. For FDDI, this value is 4500 bytes. 5 Return_Values RPC_SUCCESS Indicates success. clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_broadcast operation. 4 clnt_call A macro that calls a remote procedure. Format #include enum clnt_stat clnt_call(CLIENT *handle, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out, struct timeval timeout); 5 Arguments handle A pointer to a client handle created by any of the client-handle creation routines. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. in A pointer to the remote procedure's arguments. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. timeout A structure describing the time allowed for results to return to the client. If you have previously used the clnt_control macro with the CLSET_TIMEOUT code, this value is ignored. 5 Description Use the clnt_call macro after using one of the client-handle creation routines. After you are finished with the handle, return it using the clnt_destroy macro. Use the clnt_perror to print any errors that occurred. 5 Return_Values RPC_SUCCESS Indicates success. clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_call operation. 4 clnt_control A macro that changes or retrieves information about an RPC client process. Format #include bool_t clnt_control(CLIENT *handle, u_int code, char *info); 5 Arguments handle A pointer to a client handle created by any of the client-handle creation routines. code A code designating the type of information to be set or retrieved. info A pointer to a buffer containing the information for a SET operation or the results of a GET operation. 5 Description For UDP and TCP transports specify any of the following for code: CLSET_TIMEOUT struct Set total timeout timeval CLGET_TIMEOUT struct Get total timeout timeval CLGET_SERVER_ADDR struct Get server address sockaddr_ in CLGET_FD int Get associated socket CL_FD_CLOSE void Close socket on clnt_destroy CL_FD_NCLOSE void Leave socket open on clnt_ destroy If you set the timeout using clnt_control, ONC RPC ignores the timeout parameter in all future clnt_call calls. The default total timeout is 25 seconds. For the UDP transport two additional options are available: CLSET_RETRY_ struct Set retry timeout TIMEOUT timeval CLGET_RETRY_ struct Get retry timeout TIMEOUT timeval The timeout value in these two calls is the time that UDP waits for a response before retransmitting the message to the server. The default time is 5 seconds. The retry timeout controls when UDP retransmits the request; the total timeout controls the total time that the client should wait for a response. For example, with the default settings, UDP will retry the transmission four times at 5-second intervals. 5 Return_Values TRUE Success FALSE Failure 4 clnt_create_# Creates a client handle and returns its address. Format #include CLIENT *clnt_create(char *host, u_long prognum, u_long versnum, char *protocol); 5 Arguments host A pointer to the name of the remote host. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. protocol A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp. 5 Description The clnt_create routine creates an RPC client handle for prognum. An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol. This routine uses the Portmapper. You cannot control the local port. The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport. The retry time for the UDP transport is five seconds. Use the clnt_create routine instead of the callrpc or clnt_ broadcast routines if you want to use one of the following: o The TCP transport o A non-null authentication o More than one active client at the same time You can also use the clnttcp_create routine to use the TCP protocol, or the clntudp_create routine to use the UDP protocol. The clnt_create routine uses the global variable rpc_createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerrif you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. NOTE If the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_ create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * Client handle containing the server information. NULL Error occurred while creating the client handle. Use the clnt_pcreateerror or clnt_ spcreateerror routine to obtain diagnostic information. 4 clnt_create_vers Creates a client handle and returns its address. Seeks to use a server supporting the highest version number within a specified range. Format #include CLIENT *clnt_create_vers(char *host, u_long prognum, u_long *versnum, u_long min_vers, u_long max_vers, char *protocol); 5 Arguments host A pointer to the name of the remote host. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. This value is returned by the routine. The value is the highest version number supported by the remote server that is in the range of version numbers specified by min_vers and max_vers. The argument may remain undefined; see additional information in the Description section. min_vers The minimum acceptable version number for the remote procedure. max_vers The maximum acceptable version number for the remote procedure. protocol A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp. 5 Description The clnt_create_vers routine creates an RPC client handle for prognum. An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol. This routine uses the Portmapper. You cannot control the local port. The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport. The retry time for the UDP transport is 5 seconds. The clnt_create_vers routine differs from the standard clnt_ create routine in that it seeks out the highest version number supported by the server. If the server does not support any version numbers within the requested range, the routine returns NULL and the versnum variable is undefined. The clnt_create_vers routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. 5 Return_Values CLIENT * Clien-thandle containing the server information. NULL Error occurred while creating the client handle. Usually the error indicates that the server does not support any version numbers within the requested range. Use the clnt_ pcreateerror or clnt_spcreateerror routine to obtain diagnostic information. 4 clnt_destroy A macro that frees the memory associated with an RPC client handle. Format #include void clnt_destroy(CLIENT *handle); 5 Arguments handle A pointer to a client handle created by any of the client-handle creation routines. 5 Description The clnt_destroy routine destroys the client's RPC handle by deallocating all memory related to the handle. The client is undefined after the clnt_destroy call. If the clnt_create routine had previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_CLOSE, this routine closes the socket. If the clnt_create routine had not previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_NCLOSE, this routine leaves the socket open. 5 Return_Values None 4 clnt_freeres A macro that frees the memory that was allocated when the remote procedure's results were decoded. Format #include bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char *out); 5 Arguments handle A pointer to a client handle created by any of the client-handle creation routines. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. 5 Description The clnt_freeres routine calls the xdr_free routine to deallocate the memory where the remote procedure's results are stored. 5 Return_Values TRUE Success. FALSE Error occurred while freeing the memory. 4 clnt_geterr A macro that returns error information indicating why an RPC call failed. Format #include void clnt_geterr(CLIENT *handle, struct rpc_err *errp); 5 Arguments handle A pointer to a client handle created by any of the client-handle creation routines. errp A pointer to an rpc_err structure containing information that indicates why an RPC call failed. This information is the same information as clnt_stat contains, plus one of the following: the C error number, the range of server versions supported, or authentication errors. 5 Description This macro copies the error information from the client handle to the structure referenced by errp. The macro is mainly for diagnostic use. 5 Return_Values None 4 clnt_pcreateerror Prints a message explaining why ONC RPC could not create a client handle. Format #include void clnt_pcreateerror(char *sp); 5 Arguments sp A pointer to a string to be used as the beginning of the error message. 5 Description The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The message consists of the sp parameter followed by an RPC-generated error message. Use this routine when the clnt_create, clnttcp_ create, or clntudp_create routine fails. 5 Return_Values None 4 clnt_perrno Prints a message indicating why the callrpc or clnt_broadcast routine failed. Format #include void clnt_perrno(enum clnt_stat stat) ; 5 Arguments stat A buffer containing status information. 5 Description Prints a message to standard error corresponding to the condition indicated by the stat argument. The data type declaration for clnt_stat in rpc/rpc.h lists the standard errors. 5 Return_Values None 4 clnt_perror Prints a message explaining why an ONC RPC routine failed. Format #include void clnt_perror(CLIENT *handle, char *sp); 5 Arguments handle A pointer to the client handle used in the call that failed. sp A pointer to a string to be used as the beginning of the error message. 5 Description Prints a message to standard error indicating why an ONC RPC call failed. The message is prepended with string sp and a colon. 5 Return_Values None 4 clnt_spcreateerror Returns a message indicating why RPC could not create a client handle. Format #include char *clnt_spcreateerror(char *sp); 5 Arguments sp A pointer to a string to be used as the beginning of the error message. 5 Description The clnt_spcreateerror routine returns the address of a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use the clnt_spcreateerror routine when the clnt_create, clnttcp_ create, or clntudp_create routine fails. Use this routine if: o You want to save the string. o You do not want to use fprintf to print the message. o The message format is different from the one that clnt_perrno supports. The address that clnt_spcreateerror returns is the address of its own internal string buffer. The clnt_spcreateerror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string. 5 Return_Values char * A pointer to the message string terminated with a NULL character. NULL The routine was not able to allocate its internal buffer. 4 clnt_sperrno Returns a message indicating why the callrpc or clnt_broadcast routine failed to create a client handle. Format #include char *clnt_sperrno(enum clnt_stat stat); 5 Arguments stat A buffer containing status information. 5 Description The clnt_sperrno routine returns a pointer to a string. Use this routine instead if: o The server does not have a stderr file; many servers do not. o You want to save the string. o You do not want to use fprintf to print the message. o The message format is different from the one that clnt_perrno supports. The address that clnt_sperrno returns is a pointer to the error message string for the error. Therefore, you do not have to copy the string to your own buffer in order to save the string. 5 Return_Values char * A pointer to the message string terminated with a NULL character. 4 clnt_sperror Returns a message indicating why an ONC RPC routine failed. Format #include char *clnt_sperror(CLIENT *handle, char *sp); 5 Arguments handle A pointer to the client handle used in the call that failed. sp A pointer to a string to be used as the beginning of the error message. 5 Description The clnt_sperror routine returns a pointer to a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use this routine when the clnt_call routine fails. Use this routine if: o You want to save the string. o You do not want to use fprintf to print the message. o The message format is different from the one that clnt_perrno supports. The address that clnt_sperror returns is a pointer to its own internal string buffer. The clnt_sperror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string. 5 Return_Values char * A pointer to the message string terminated with a NULL character. NULL The routine was not able to allocate its internal buffer. 4 clntraw_create Creates a client handle for memory-based ONC RPC for simple testing and timing. Format #include CLIENT *clntraw_create(u_long prognum, u_long versnum); 5 Arguments prognum The program number associated with the remote program. versnum The version number associated with the remote program. 5 Description Creates an in-program ONC RPC client for the remote program prognum, version versnum. The transport used to pass messages to the service is actually a buffer within the process's address space, so the corresponding server should live in the same address space; see svcraw_create. This allows simulation of and acquisition of ONC RPC overheads, such as round-trip times, without any kernel interference. 5 Return_Values CLIENT * A pointer to a client handle. NULL Indicates failure. 4 clnttcp_create Creates an ONC RPC client handle for a TCP/IP connection. Format #include CLIENT *clnttcp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, int *sockp, u_int sendsize, u_int recvsize); 5 Arguments addr A pointer to a buffer containing the Internet address where the remote program is located. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. sockp A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp. sendsize The size of the send buffer. If you specify zero, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify zero, the routine chooses a suitable default. 5 Description Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses TCP/IP as a transport. The routine is similar to the clnt_create routine, except clnttcp_create allows you to specify a socket and the send and receive buffer sizes. If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening. The clnttcp_create routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file. The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp. The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary. NOTE If the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_ create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * A pointer to the client handle. NULL Indicates failure. 4 clntudp_bufcreate Creates an ONC RPC client handle for a buffered I/O UDP connection. Format #include CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp, u_int sendsize, u_int recvsize); 5 Arguments addr A pointer to a buffer containing the Internet address where the remote program is located. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. wait The amount of time used between call retransmission if no response is received. Retransmission occurs until the ONC RPC calls time out. sockp A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp. sendsize The size of the send buffer. If you specify zero, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify zero, the routine chooses a suitable default. 5 Description Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses UDP as the transport. The routine is similar to the clnt_create routine, except clntudp_bufcreate allows you to specify a socket, the UDP retransmission time, and the send and receive buffer sizes. If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening. The clntudp_bufcreate routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file. The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp. The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary. NOTE If addr->sin_port is 0 and the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * A pointer to the client handle. NULL Indicates failure. 4 clntudp_create Creates an ONC RPC client handle for a nonbuffered I/O UDP connection. Format #include CLIENT *clntudp_create(struct sockaddr_in *addr, u_long prognum, u_long versnum, struct timeval wait, register int *sockp); 5 Arguments addr A pointer to a buffer containing the Internet address where the remote program is located. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. wait The amount of time used between call retransmission if no response is received. Retransmission occurs until the ONC RPC calls time out. sockp A pointer to the socket number to be used for the remote procedure call. If sockp is RPC_ANYSOCK, then this routine opens a new socket and sets sockp. 5 Description Creates an ONC RPC client handle for the remote program prognum, version versnum at address addr. The client uses UDP as the transport. The routine is similar to the clnt_create routine, except clntudp_create allows you to specify a socket and the UDP retransmission time. If you specify the port number as zero by using addr->sin_port, the Portmapper provides the number of the port on which the remote program is listening. The clntudp_create routine uses the global variable rpc_ createerr. rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed. The rpc_createerr variable is defined in the CLNT.H file. The socket referenced by sockp is copied into a private area for RPC to use. It is the client's responsibility to close the socket referenced by sockp. The authentication scheme for the client, client->cl_auth, gets set to null authentication. The calling program can set this to something different if necessary. NOTES Since UDP/IP messages can only hold up to 8 KB of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. If addr->sin_port is 0 and the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_create_vers routine if you want to avoid this condition. 5 Return_Values CLIENT * A pointer to the client handle. NULL Indicates failure. 4 get_myaddress Returns the local host's Internet address. Format #include void get_myaddress(struct sockaddr_in *addr); 5 Arguments addr A pointer to a sockaddr_in structure that the routine will load with the Internet address of the host where the local procedure resides. 5 Description Puts the local host's Internet address into addr without doing any name translation. The port number is always set to htons (PMAPPORT). 5 Return_Values None 4 get_myaddr_dest Returns the local host's Internet address according to a destination address. Format #include void get_myaddr_dest(struct sockaddr_in *addr, struct sockaddr_in *dest); 5 Arguments addr A pointer to a sockaddr_in structure that the routine will load with the local Internet address that would provide a connection to the remote address specified in dest. dest A pointer to a sockaddr_in structure containing an Internet address of a remote host. 5 Description Since the local host may have multiple network addresses (each on its own interface), this routine is used to select the local address that would provide a connection to the remote address specified in dest. This is an alternative to gethostbyname, which invokes yellow pages. It takes a destination (where we are trying to get to) and finds an exact network match to go to. 5 Return_Values None 3 RPC_Portmapper_Routines Portmapper routines allow C programs to access the Portmapper network service. Important: In order to maintain uniqueness for the OpenVMS HELP utility, some XDR routines have a "_#" appended at the end. Do not use the "_#" when coding the routine in a program. 4 pmap_getmaps_# Returns a copy of the current port mappings on a remote host. Format #include struct pmaplist *pmap_getmaps(struct sockaddr_in *addr); 5 Arguments addr A pointer to a sockaddr_in structure containing the Internet address of the host whose Portmapper you want to call. 5 Description A client interface to the Portmapper, which returns a list of the current ONC RPC program-to-port mappings on the host located at the Internet address addr. The SHOW PORTMAPPER management command uses this routine. 5 Return_Values struct pmaplist * A pointer to the returned list of server-to- port mappings on host addr. NULL Indicates failure. 4 pmap_getmaps_vms Returns a copy of the current port mappings on a remote host running TCP/IP Services software. Format #include struct pmaplist_vms *pmap_getmaps_vms(struct sockaddr_in *addr); 5 Arguments addr A pointer to a sockaddr_in structure containing the Internet address of the host whose Portmapper you wish to call. 5 Description This routine is similar to the pmap_getmaps routine. However, pmap_getmaps_vms also returns the process identifiers (PIDs) that are required for mapping requests to TCP/IP Services hosts. 5 Return_Values struct pmaplist * A pointer to the returned list of server-to- port mappings on host addr. NULL Indicates failure. 4 pmap_getport Returns the port number on which the specified service is waiting. Format #include u_short pmap_getport(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long protocol ); 5 Arguments addr A pointer to a sockaddr_in structure containing the Internet address of the host where the remote Portmapper resides. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. protocol The transport protocol that the remote procedure uses. Specify either IPPROTO_UDP or IPPROTO_TCP. 5 Description A client interface to the Portmapper. This routine returns the port number on which waits a server that supports program number prognum, version versnum, and speaks the transport protocol associated with protocol (IPPROTO_UDP or IPPROTO_TCP). NOTES If the requested version is not available, but at least the requested program is registered, the routine returns a port number. The pmap_getport routine returns the port number in host byte order not network byte order. For certain routines you may need to convert this value to network byte order using the htons routine. For example, the sockaddr_in structure requires that the port number be in network byte order. 5 Return_Values x The port number of the service on the remote system. 0 No mapping exists or RPC could not contact the remote Portmapper service. In the latter case, the global variable rpc_createerr.cf_error contains the ONC RPC status. 4 pmap_rmtcall The client interface to the Portmapper service for a remote call and broadcast service. This routine allows a program to do a lookup and call in one step. Format #include enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char * in xdrproc_t outproc, char * out, struct timeval timeout, u_long *port ); 5 Arguments addr A pointer to a sockaddr_in structure containing the Internet address of the host where the remote Portmapper resides. prognum The program number associated with the remote procedure. versnum The version number associated with the remote procedure. procnum The procedure number associated with the remote procedure. inproc The XDR routine used to encode the remote procedure's arguments. in A pointer to the remote procedure's arguments. outproc The XDR routine used to decode the remote procedure's results. out A pointer to the remote procedure's results. timeout A timeval structure describing the time allowed for the results to return to the client. port A pointer to a location for the returned port number. Modified to the remote program's port number if the pmap_rmtcall routine succeeds. 5 Description A client interface to the Portmapper, which instructs the Portmapper on the host at the Internet address *addr to make a call on your behalf to a procedure on that host. Use this procedure for a ping operation and nothing else. You can use the clnt_perrno routine to print any error message. NOTE If the requested procedure is not registered with the remote Portmapper, the remote Portmapper does not reply to the request. The call to pmap_rmtcall will eventually time out. The pmap_rmtcall does not perform authentication. 5 Return_Values enum clnt_stat Returns the buffer containing the status of the operation. 4 pmap_set Called by the server procedure to have the Portmapper create a mapping of the procedure's program and version number. Format #include bool_t pmap_set(u_long prognum, u_long versnum, u_long protocol, u_short port); 5 Arguments prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. protocol The transport protocol that the server procedure uses. Specify either IPPROTO_UDP or IPPROTO_TCP. port The port number associated with the server program. 5 Description A server interface to the Portmapper, which establishes a mapping between the triple [prognum,versnum,protocol] and port on the server's Portmapper service. The svc_register routine calls this routine to register the server with the local Portmapper. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 pmap_unset Called by the server procedure to have the Portmapper delete a mapping of the procedure's program and version number. Format #include bool_t pmap_unset(u_long prognum, u_long versnum); 5 Arguments prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. 5 Description A server interface to the Portmapper, which destroys all mapping between the triple [prognum, versnum, *] and ports on the local host's Portmapper. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 3 RPC_Server_Routines Server routines allow C programs to receive procedure calls from client programs over the network. 4 registerrpc Obtains a unique systemwide procedure identification number. Format #include int registerrpc(u_long prognum, u_long versnum, u_long procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t outproc ); 5 Arguments prognum The program number associated with the service procedure. versnum The version number associated with the service procedure. procnum The procedure number associated with the service procedure. progname The address of the service procedure being registered with the ONC RPC service package. inproc The XDR routine used to decode the service procedure's arguments. outproc The XDR routine used to encode the service procedure's results. 5 Description The registerrpc routine performs the following tasks for a server: o Creates a UDP server handle. See the svcudp_create routine for restrictions. o Calls the svc_register routine to register the program with the Portmapper. o Adds prognum, versnum, and procnum to an internal list of registered procedures. When the server receives a request, it uses this list to determine which routine to call. A server should call registerrpc for every procedure it implements, except for the NULL procedure. If a request arrives for program prognum, version versnum, and procedure procnum, progname is called with a pointer to its parameters. 5 Return_Values 0 Indicates success. -1 Indicates failure. 4 seterr_reply Fills in the error text in a reply message. Format #include void seterr_reply(struct rpc_msg *msg, struct rpc_err *error); 5 Arguments msg A pointer to a reply message buffer. error A pointer to an rpc_err structure containing the error associated with the reply message. 5 Description Given a reply message, seterr_reply fills in the error field. 5 Return_Values None 4 svc_destroy A macro that frees the memory associated with an RPC server handle. Format #include void svc_destroy(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description The svc_destroy routine returns all the private data structures associated with a server handle. If the server-handle creation routine received the value RPC_ANYSOCK as the socket, svc_destroy closes the socket. Otherwise, your program must close the socket. 5 Return_Values None 4 svc_freeargs A macro that frees the memory allocated when the procedure's arguments were decoded. Format #include bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. inproc The XDR routine used to decode the service procedure's arguments. in A pointer to the service procedure's decoded arguments. 5 Description The svc_destroy routine returns the memory that the svc_getargs routine allocated to hold the service procedure's decoded arguments. This routine calls the xdr_free routine. 5 Return_Values TRUE Success; memory successfully deallocated. FALSE Failure; memory not deallocated. 4 svc_getargs A macro that decodes the service procedure's arguments. Format #include bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. inproc The XDR routine used to decode the service procedure's arguments. in A pointer to the service procedure's decoded arguments. 5 Description This routine calls the specified XDR routine to decode the arguments passed to the service procedure. 5 Return_Values TRUE Successfully decoded. FALSE Decoding unsuccessful. 4 svc_getcaller A macro that returns the address of the client that called the service procedure. Format #include struct sockaddr_in *svc_getcaller(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description This routine returns a sockaddr_in structure containing the Internet address of the RPC client routine that called the service procedure. 5 Return_Values struct sockaddr_ A pointer to the socket descriptor. in 4 svc_getreqset Returns data for each server connection. Format #include void svc_getreqset(fd_set *rdfds); 5 Arguments rdfds A pointer to the read file descriptor bit mask modified by the select routine. 5 Description The svc_getreqset routine is for servers that implement custom asynchronous event processing or that do not use the svc_run routine. You can only use svc_fdset when the server does not use svc_run. You are unlikely to call this routine directly, because the svc_run routine calls it. However, there are times when you cannot call svc_run. For example, suppose a program services RPC requests and reads or writes to another socket at the same time. The program cannot call svc_run. It must call select and svc_getreqset. The server calls svc_getreqset when a call to the select system call determines that the server has received one or more RPC requests. The svc_getreqset routine reads in data for each server connection, then calls the server program to handle the data. The svc_getreqset routine does not return a value. It finishes executing after all sockets associated with the variable rdfds have been serviced. You can use the global variable svc_fdset with svc_getreqset. The svc_fdset variable is the RPC server's read file descriptor bit mask. To use svc_fdset: 1. Copy the global variable svc_fdset into a temporary variable. 2. Pass the temporary variable to the select routine. The select routine overwrites the variable and returns it. 3. Pass the temporary variable to the svc_getreqset routine. 5 Example #define MAXSOCK 10 int readfds[ MAXSOCK+1], /* sockets to select from*/ i, j; for(i = 0, j = 0; i << MAXSOCK; i++) if((svc_fdset[i].sockname != 0) && (svc_ fdset[i].sockname != -1)) readfds[j++] = svc_fdset[i].sockname; readfds[j] = 0; /* list of sockets ends with a zero */ switch(select(0, readfds, 0, 0, 0)) { case -1: /* an error happened */ case 0: /* time out */ break; default: /* 1 or more sockets ready for reading */ errno = 0; svc_getreqset(readfds); if( errno == ENETDOWN || errno == ENOTCONN) sys$exit( SS$_THIRDPARTY); } 5 Return_Values None 4 svc_register Registers the server program with the Portmapper service. Format #include bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long versnum, void (*dispatch)(), u_long protocol); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. dispatch The address of the service dispatch procedure that the server procedure calls. The procedure dispatch has the following form: void dispatch(request, xprt) struct svc_req *request; SVCXPRT *xprt; The svc_run and svc_getreqset call the dispatch routine. protocol The protocol that the server procedure uses. Values for this parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is zero, the service is not registered with the Portmapper service. 5 Description Associates prognum and versnum with the service dispatch procedure dispatch. If protocol is nonzero, then a mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is also established with the local Portmapper service. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 svc_run Waits for incoming RPC requests and calls the svc_getreqset routine to dispatch to the appropriate RPC server program. Format #include void svc_run(); 5 Arguments None 5 Description The svc_run routine calls the select routine to wait for RPC requests. When a request arrives, svc_run calls the svc_getreqset routine. Then svc_run calls the select routine again. The svc_run routine never returns. You may use the global variable svc_fdset with the svc_run routine. See the svc_getreqset routine for more information about svc_fdset. 5 Return_Values Never returns 4 svc_sendreply Sends the results of a remote procedure call to an RPC client. Format #include bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. outproc The XDR routine used to encode the server procedure's results. out A pointer to the server procedure's results. 5 Description Called by an ONC RPC service's dispatch routine to send the results of a remote procedure call. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 svc_unregister Calls the Portmapper to unregister the specified program and version for all protocols. The program and version are removed from the list of active servers. Format #include void svc_unregister(u_long prognum, u_long versnum); 5 Arguments prognum The program number associated with the server procedure. versnum The version number associated with the server procedure. 5 Description Removes all mapping of the double [prognum, versnum] to dispatch routines, and of the triple [prognum, versnum, *] to port number. 5 Return_Values None 4 svcerr_auth Sends an authentication error to the client. Format #include void svcerr_auth(SVCXPRT *xprt, enum auth_stat why); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. why The reason for the authentication error. 5 Description Called by a service dispatch routine that refuses to perform a remote procedure call because of an authentication error. 5 Return_Values None 4 svcerr_decode Sends an error code to the client indicating that the server procedure cannot decode the client's arguments. Format #include void svcerr_decode(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Called by a service dispatch routine that cannot successfully decode its parameters. See also the svc_getargs routine. 5 Return_Values None 4 svcerr_noproc Sends an error code to the client indicating that the server program does not implement the requested procedure. Format #include void svcerr_noproc(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Called by a service dispatch routine that does not implement the procedure number that the client requested. 5 Return_Values None 4 svcerr_noprog Sends an error code to the client indicating that the server program is not registered with the Portmapper. Format #include void svcerr_noprog(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Called when the desired program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a server is not registered. Therefore, service implementors usually do not use this routine. 5 Return_Values None 4 svcerr_progvers Sends an error code to the client indicating that the requested program is registered with the Portmapper but the requested version of the program is not registered. Format #include void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long high_vers); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. low_vers The lowest version of the requested program that the server supports. high_vers The highest version of the requested program that the server supports. 5 Description Called when the desired version of a program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a requested program version is not registered. Therefore, service implementors usually do not use this routine. 5 Return_Values None 4 svcerr_systemerr Sends an error code to the client indicating that an error occurred that is not handled by the protocol being used. Format #include void svcerr_systemerr(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. 5 Return_Values None 4 svcerr_weakauth Sends an error code to the client indicating that an authentication error occurred. The authentication information was correct but was insufficient. Format #include void svcerr_weakauth(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Called by a service dispatch routine that refuses to perform a remote procedure call because of insufficient (but correct) authentication parameters. The routine calls svcerr_auth (xprt, AUTH_TOOWEAK). 5 Return_Values None 4 svcraw_create Creates a server handle for memory-based ONC RPC for simple testing and timing. Format #include SVCXPRT *svcraw_create(); 5 Arguments None 5 Description Creates a in-program ONC RPC service transport, to which it returns a pointer. The transport is really a buffer within the process's address space, so the corresponding client should live in the same address space; see the clntraw_create routine. The svcraw_create and clntraw_create routines allow simulation and acquisition of ONC RPC overheads (such as round-trip times), without any kernel interference. 5 Return_Values SVCXPRT * A pointer to an RPC server handle for the in-memory transport. NULL Indicates failure. 4 svcfd_create Creates an RPC server handle using the specified open file descriptor. Format #include SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize); 5 Arguments fd The number of an open file descriptor. sendsize The size of the send buffer. If you specify zero, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify zero, the routine chooses a suitable default. 5 Description Creates an RPC server handle using the specified TCP socket, to which it returns a pointer. The server should call the svcfd_ create routine after it accepts an incoming TCP connection. 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 svctcp_create Creates an ONC RPC server handle for a TCP/IP connection. Format #include SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int recvsize); 5 Arguments sock The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. sendsize The size of the send buffer. If you specify zero, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify zero, the routine chooses a suitable default. 5 Description Creates an RPC server handle using the TCP/IP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls). 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 svcudp_bufcreate Creates an ONC RPC server handle for a buffered I/O UDP connection. Format #include SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int recvsize); 5 Arguments sock The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. sendsize The size of the send buffer. If you specify zero, the routine chooses a suitable default. recvsize The size of the receive buffer. If you specify zero, the routine chooses a suitable default. 5 Description Creates an RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls). 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 svcudp_create Creates an ONC RPC server handle for a nonbuffered I/O UDP connection. Format #include SVCXPRT *svcudp_create(int sock); 5 Arguments sock The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. 5 Description Creates an RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls). NOTE Since UDP/IP-based ONC RPC messages can only hold up to 8 KB of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. 5 Return_Values SVCXPRT * A pointer to the server handle. NULL Indicates failure. 4 xprt_register Adds a socket associated with an RPC server handle to the list of registered sockets. Format #include void xprt_register(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Activation of a transport handle involves setting the most appropriate bit for the socket associated with xprt in the svc_ fds mask. When svc_run() is invoked, activity on the transport handle is eligible to be processed by the server. The svc_register routine calls this routine; therefore, you are unlikely to use this routine directly. 5 Return_Values None 4 xprt_unregister Removes a socket associated with an RPC server handle from the list of registered sockets. Format #include void xprt_unregister(SVCXPRT *xprt); 5 Arguments xprt A pointer to an RPC server handle created by any of the server- handle creation routines. 5 Description Removes the socket associated with the indicated handle from the list of registered sockets maintained in the svc_fdset variable. Activity on the socket associated with xprt will no longer be checked by the svc_run routine. The svc_unregister routine calls this routine; therefore, you are unlikely to use this routine directly. 5 Return_Values None 4 _authenticate Authenticates the request message. Format #include enum auth_stat _authenticate(struct svc_req *rqst, struct rpc_msg *msg); 5 Arguments rqst A pointer to an svc_req structure with the requested program number, procedure number, version number, and credentials passed by the client. msg A pointer to an rpc_msg structure with members that make up the RPC message. 5 Description Returns AUTH_OK if the message is authenticated successfully. If it returns AUTH_OK, the routine also does the following: o Sets rqst->rq_xprt->verf to the appropriate response verifier. o Sets rqst->rq_client_cred to the "cooked" form of the credentials. The expression rqst->rq_xprt->verf must be preallocated and its length must be set appropriately. The program still owns and is responsible for msg->u.cmb.cred and msg->u.cmb.verf. The authentication system retains ownership of rqst->rq_client_cred, the "cooked" credentials. 5 Return_Values enum auth_stat The return status code for the authentication checks: AUTH_OK=0-Authentication checks successful. AUTH_BADCRED=1-Invalid credentials (seal broken) AUTH_REJECTEDCRED=2-Client should begin new session AUTH_BADVERF=3-Invalid verifier (seal broken) AUTH_REJECTEDVERF=4-Verifier expired or was replayed AUTH_TOOWEAK=5-Rejected for security reasons AUTH_INVALIDRESP=6-Invalid response verifier AUTH_FAILED=7-Some unknown reason 3 RPC_XDR_Routines XDR routines specify external data representation. They allow C programmers to describe arbitrary data structures in a system- independent fashion. Important: In order to maintain uniqueness for the OpenVMS HELP utility, some XDR routines have a "_#" appended at the end. Do not use the "_#" when coding the routine in a program. 4 xdr_accepted_reply Serializes and deserializes a message-accepted indication in an RPC reply message. Format #include bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *arp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. arp A pointer to a buffer to which the message-accepted indication is written. 5 Description Used for encoding reply messages. This routine encodes the status of the RPC call and, in the case of success, the call results as well. This routine is useful for users who want to generate messages without using the ONC RPC package. It returns the message-accepted variant of a reply message union in the arp argument. The xdr_replymsg routine calls this routine. 5 Return_Values TRUE Indicates success. FALSE Indicates failure to encode the message. 4 xdr_array Serializes and deserializes the elements of a variable-length array. Format #include bool_t xdr_array(XDR *xdrs, char **arrp, u_int *sizep, u_int maxsize, u_int elsize, xdrproc_t elproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. arrp A pointer to the pointer to the array. sizep A pointer to the number of elements in the array. This element count cannot exceed the maxsize parameter. maxsize The maximum size of the sizep parameter. This value is the maximum number of elements that the array can hold. elsize The size, in bytes, of each of the array's elements. elproc The XDR routine to call that handles each element of the array. 5 Description A filter primitive that translates between variable-length arrays and their corresponding external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_authunix_parms Serializes and deserializes credentials in an authentication parameter structure. Format #include bool_t xdr_authunix_parms (XDR *xdrs, struct authunix_parms *authp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. authp A pointer to an authunix_parms structure. 5 Description Used for externally describing standard UNIX credentials. On a TCP/IP Services host, this routine encodes the host name, the user ID, and the group ID. It sets the group ID list to NULL. This routine is useful for users who want to generate these credentials without using the ONC RPC authentication package. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_bool Serializes and deserializes boolean data. Format #include bool_t xdr_bool (XDR *xdrs, bool_t *bp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. bp A pointer to the boolean data. 5 Description A filter primitive that translates between booleans (integers) and their external representations. When encoding data, this filter produces values of either 1 or 0. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_bytes Serializes and deserializes a counted byte array. Format #include bool_t xdr_bytes (XDR *xdrs, char **bpp, u_int *sizep, u_int maxsize); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. bpp A pointer to a pointer to the byte array. sizep A pointer to the length of the byte array. maxsize The maximum size of the length of the byte array. 5 Description A filter primitive that translates between a variable-length byte array and its external representation. The length of the array is located at sizep; the array cannot be longer than maxsize. If *bpp is NULL, xdr_bytes allocates maxsize bytes. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_callhdr Serializes and deserializes the static part of a call message header. Format #include bool_t xdr_callhdr(XDR *xdrs, struct rpc_msg *chdrp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. chdrp A pointer to the call header data. 5 Description Describes call header messages. This routine is useful for users who want to generate messages without using the ONC RPC package. The xdr_callhdr routine encodes the following fields: transaction ID, direction, RPC version, server program number, and server version. 5 Return_Values TRUE Indicate success. FALSE Indicates failure. 4 xdr_callmsg Serializes and deserializes an ONC RPC call message. Format #include bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsgp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. cmsgp A pointer to an rpc_msg structure that describes the RPC call message. 5 Description This routine is useful for users who want to generate messages without using the ONC RPC package. The xdr_callmsg routine encodes the following fields: transaction ID, direction, RPC version, server program number, server version number, server procedure number, and client authentication. The pmap_rmtcall and svc_sendreply routines call xdr_callmsg. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_char Serializes and deserializes character data. Format #include bool_t xdr_char(XDR *xdrs, char *cp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. cp A pointer to a character. 5 Description A filter primitive that translates between internal representations of characters and their XDR representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_double Serializes and deserializes VAX and IEEE double-precision floating-point numbers. Format #include bool_t xdr_double(XDR *xdrs, double *dp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. dp A pointer to the double-precision floating-point number. 5 Description A filter primitive that translates between double-precision numbers and their external representations. This routine is implemented by four XDR routines: xdr_ Converts VAX D-format floating-point numbers. double_D xdr_ Converts VAX G-format floating-point numbers. double_G xdr_ Converts IEEE T-format floating-point numbers. double_T xdr_ Converts IEEE X-format floating-point numbers. double_X You can reference these routines explicitly or you can use compiler settings to control which routine is used when you reference the xdr_double routine. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_enum Serializes and deserializes enumerations. Format #include bool_t xdr_enum(XDR *xdrs, enum_t *ep); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. ep A pointer to the enumeration data. 5 Description A filter primitive that translates between enumerations (actually integers) and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_float Serializes and deserializes VAX and IEEE single-precision floating-point numbers. Format #include bool_t xdr_float(XDR *xdrs, float *fp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. fp A pointer to a single-precision floating-point number. 5 Description A filter primitive that translates between single-precision floating-point numbers and their external representations. This routine is implemented by two XDR routines: xdr_ Converts VAX F-format floating-point numbers. float_F xdr_ Converts IEEE T-format floating-point numbers. float_S You can reference these routines explicitly or you can use compiler settings to control which routine is used when you reference the xdr_float routine. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_free Deallocates the memory associated with the indicated data structure. Format #include bool_t xdr_free(xdrproc_t proc, char *objp); 5 Arguments proc The XDR routine for the data structure being freed. objp A pointer to the data structure to be freed. 5 Description Releases memory allocated for the data structure to which objp points. The pointer passed to this routine is not freed, but what it points to is freed (recursively). Use this routine to free decoded data that is no longer needed. Never use this routine for encoded data. 5 Return_Values TRUE Indicate success. FALSE Indicates failure. 4 xdr_hyper Serializes and deserializes VAX quadwords (known in XDR as hyperintegers). Format #include bool_t xdr_hyper(XDR *xdrs, quad *hp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. hp A pointer to the hyperinteger data. 5 Description A filter primitive that translates between hyperintegers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_int Serializes and deserializes integers. Format #include bool_t xdr_int(XDR *xdrs, int *ip); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. ip A pointer to the integer data. 5 Description A filter primitive that translates between integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_long Serializes and deserializes long integers. Format #include bool_t xdr_long(XDR *xdrs, long *lp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. lp A pointer to a long integer. 5 Description A filter primitive that translates between long integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_opaque Serializes and deserializes opaque structures. Format #include bool_t xdr_opaque(XDR *xdrs, char *op, u_int cnt); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. op A pointer to the opaque data. cnt The size of op in bytes. 5 Description A filter primitive that translates between fixed-size opaque data and its external representation. This routine treats the data as a fixed length of bytes and does not attempt to convert the bytes. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_opaque_auth Serializes and deserializes ONC RPC authentication information message. Format #include bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *authp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. authp A pointer to an opaque_auth structure describing authentication information. The pointer should reference data created by the authnone_create, authunix_create, or authunix_create_default routine. 5 Description Translates ONC RPC authentication information messages. This routine is useful for users who want to generate messages without using the ONC RPC package. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmap_# Serializes and deserializes Portmapper parameters. Format #include bool_t xdr_pmap(XDR *xdrs, struct pmap *regs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. regs A pointer to the pmap structure. This structure contains the program number, version number, protocol number, and port number. 5 Description Describes parameters to various Portmapper procedures, externally. This routine is useful for users who want to generate these parameters without using the Portmapper interface. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmap_vms Serializes and deserializes OpenVMS specific Portmapper parameters. Format #include bool_t xdr_pmap_vms(XDR *xdrs, struct pmap_vms *regs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. regs A pointer to the pmap_vms structure. This structure contains the program number, version number, protocol number, port number and the OpenVMS specific process identification. 5 Description This routine is similar to xdr_pmap(), except it also includes the process identification in the pmap_vms structure. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmaplist_# Serializes and deserializes a list of Portmapper port mappings. Format #include bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rpp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. rpp A pointer to a pointer to a pmaplist structure containing a list of Portmapper programs and their respective information. If the routine is used to decode a Portmapper listing, it sets rpp to the address of a newly allocated linked list of pmaplist structures. 5 Description Describes a list of port mappings, externally. This routine is useful for users who want to generate these parameters without using the Portmapper interface. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pmaplist_vms Serializes and deserializes a list of Portmapper port mappings for OpenVMS systems. Format #include bool_t xdr_pmaplist_vms (XDR *xdrs, struct pmaplist_vms **rpp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. rpp A pointer to a pointer to a pmaplist_vms structure containing a list of Portmapper programs and their respective information, including OpenVMS-specific information. 5 Description This routine is similar to the xdr_pmaplist routine, except that it also includes the process identification in the pmaplist_vms structure. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_pointer Serializes and deserializes indirect pointers and the data being pointed to. Format #include bool_t xdr_pointer(XDR *xdrs, char **objpp, u_int objsize, xdrproc_t objproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. objpp A pointer to a pointer to the data being converted. objsize The size of the data structure in bytes. objproc The XDR procedure that filters the structure between its local form and its external representation. 5 Description An XDR routine for translating data structures that contain pointers to other structures, such as a linked list. The xdr_ pointer routine is similar to the xdr_reference routine. The differences are that the xdr_pointer routine handles pointers with the value NULL and that it translates the pointer values to a boolean. If the boolean is TRUE, the data follows the boolean. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_reference Serializes and deserializes indirect pointers and the data being pointed to. Format #include bool_t xdr_reference(XDR *xdrs, char **objpp, u_int objsize, xdrproc_t objproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. objpp A pointer to a pointer to the structure containing the data being converted. If objpp is zero, the xdr_reference routine allocates the necessary storage when decoding. This argument must be nonzero during encoding. objsize The size of the structure in bytes. objproc The XDR procedure that filters the structure between its local form and its external representation. 5 Description A primitive that provides pointer chasing within structures. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_rejected_reply Serializes and deserializes the remainder of an RPC reply message after the header indicates that the reply is rejected. Format #include bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rrp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. rrp A pointer to the rejected_reply structure describing the rejected reply message. 5 Description Describes ONC RPC reply messages. This routine is useful for users who want to generate messages without using the ONC RPC package. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_replymsg Serializes and deserializes the RPC reply header and then calls the appropriate routine to interpret the rest of the message. Format #include bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsgp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. rmsgp A pointer to the rpc_msg structure describing the reply message. 5 Description Describes ONC RPC reply messages. This routine is useful for users who want to generate messages without using the ONC RPC package. This routine interprets the message header and then calls either the xdr_accepted_reply or the xdr_rejected_reply routine to interpret the body of the RPC message. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_short Serializes and deserializes short integers. Format #include bool_t xdr_short(XDR *xdrs, short *sp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. sp A pointer to a short integer. 5 Description A filter primitive that translates between short integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_string Serializes and deserializes strings (arrays of bytes terminated by a NULL character). Format #include bool_t xdr_string(XDR *xdrs, char **spp, u_int maxsize); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. spp A pointer to a pointer to a character string. maxsize The maximum size of the string. 5 Description A filter primitive that translates between strings and their corresponding external representations. Strings cannot be longer than the value specified with the maxsize parameter. While decoding, if *spp is NULL, this routine allocates the necessary storage to hold the NULL-terminated string and sets *spp to point to the allocated storage. This routine is the same as the xdr_wrapstring routine, except that this routine allows you to specify maxsize. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_char Serializes and deserializes unsigned characters. Format #include bool_t xdr_u_char(XDR *xdrs, char *ucp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. ucp A pointer to a character. 5 Description A filter primitive that translates between internal representation of unsigned characters and their XDR representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_hyper Serializes and deserializes unsigned VAX quadwords (known in XDR as hyperintegers). Format #include bool_t xdr_u_hyper(XDR *xdrs, unsigned quad *uhp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. uhp A pointer to the unsigned hyperinteger. 5 Description A filter primitive that translates between unsigned hyperintegers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_int Serializes and deserializes unsigned integers. Format #include bool_t xdr_u_int(XDR *xdrs, unsigned *uip); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. uip A pointer to the unsigned integer. 5 Description A filter primitive that translates between unsigned integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_long Serializes and deserializes unsigned long integers. Format #include bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. ulp A pointer to the unsigned long integer. 5 Description A filter primitive that translates between unsigned long integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_u_short Serializes and deserializes unsigned short integers. Format #include bool_t xdr_u_short(XDR *xdrs, unsigned short *usp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. usp A pointer to the unsigned short integer. 5 Description A filter primitive that translates between unsigned short integers and their external representations. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_union Serializes and deserializes discriminant unions. Format #include bool_t xdr_union(XDR *xdrs, enum *dscmp, char *unp, struct xdr_discrim *choices, xdrproc_t default); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. dscmp A pointer to the union's discriminant. unp A pointer to the union's data. choices A pointer to an array of xdr_discrim structures. Each structure contains an ordered pair of [value,proc]. The final structure in the array is denoted by a pointer with the value NULL. default The address of the default XDR routine to call if the dscmp argument is not found in the choices array. 5 Description A filter primitive that translates between a discriminated union and its corresponding external representation. The xdr_union routine first translates the discriminant of the union located at dscmp. This discriminant is always of type enum_t. Next, the routine translates the union data located at unp. To translate the union data the xdr_union routine first searches the structure pointed to by the choices argument for the union discriminant passed in the dscmp argument. If a match is found, the xdr_union routine calls proc to translate the union data. The end of the xdr_discrim structure array must contain an entry with the value NULL for proc. If the xdr_union routine reaches this entry before finding a match, the routine calls the default procedure (if it is not NULL). 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_vector Serializes and deserializes the elements of a fixed-length array (known as a vector). Format #include bool_t xdr_vector(XDR *xdrs, char **vecpp, u_int elnum, u_int elsize, xdrproc_t elproc); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. vecpp A pointer to a pointer to the array. elnum The number of elements in the array. elsize The size, in bytes, of each element. elproc The XDR routine to handle each element. 5 Description A routine that calls elproc to prepare the elements of an array for XDR messages. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdr_void When there is no data to convert, this routine is passed to ONC RPC routines that require an XDR procedure parameter. Format #include bool_t xdr_void(); 5 Description This routine is used as a placeholder for a program that passes no data in a remote procedure call. Most client and server routines expect an XDR routine to be called, even when there is no data to pass. 5 Return_Values This routine always returns TRUE. 4 xdr_wrapstring Serializes and deserializes NULL-terminated strings. Format #include bool_t xdr_wrapstring(XDR *xdrs, char **spp); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. spp A pointer to a pointer to a string. 5 Description A primitive that calls xdr_string(xdrs, sp, MAXUNSIGNED), where MAXUNSIGNED is the maximum value of an unsigned integer. This routine is useful because the ONC RPC client and server routines pass the XDR stream handle and a single pointer as parameters to any referenced XDR routines. The xdr_string routine, one of the most frequently used ONC RPC primitives, requires three parameters. While decoding, if *sp is NULL, the necessary storage is allocated to hold the NULL-terminated string and *sp is set to point to it. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdrmem_create Initializes an XDR stream descriptor for a memory buffer. Format #include void xdrmem_create(XDR *xdrs, char *addr, u_int size, enum xdr_op op); 5 Arguments xdrs A pointer to the XDR stream handle being created. The routine xdrmem_create fills in xdrs with encoding and decoding information. addr A pointer to the memory buffer. size The length of the memory buffer. op An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE. 5 Description The stream handle xdrs is initialized with the operation op, the buffer addr and size, and the operations context for an xdrmem stream. 5 Return_Values None 4 xdrrec_create Initializes a record-oriented XDR stream descriptor. Format #include void xdrrec_create(XDR *xdrs, u_int sendsize, u_int recvsize, char *tcp_handle, int (*readit)(), int (*writeit)()); 5 Arguments xdrs A pointer to the XDR stream handle being created. The routine xdrrec_create fills in xdrs with encoding and decoding information. sendsize The send buffer size. recvsize The receive buffer size. tcp_handle A pointer to an opaque handle that is passed as the first parameter to the procedures (*readit)() and (*writeit)(). (*readit)() Read procedure that takes the opaque handle tcp_handle. The routine must use the following format: int readit(char *tcp_handle, char *buffer, u_long len) where tcp_handle is the client or server handle, buffer is the buffer to fill, and len is the number of bytes to read. The readit routine should return either the number of bytes read or the value -1 if an error occurs. (*writeit)() Write procedure that takes the opaque handle tcp_handle. The routine must use the following format: int writeit(char *tcp_handle, char *buffer, u_long len) where tcp_handle is the client or server handle, buffer is the buffer to write, and len is the number of bytes to write. The readit routine should return either the number of bytes written or the value -1 if an error occurs. 5 Description The stream descriptor for xdrs initializes the maximum allowable size for a request recvsize and reply sendsize, the addresses of the routine to perform the read (readit) and write (writeit), and the TCP handle used for network I/O. 5 Return_Values None 4 xdrrec_endofrecord Generates an end-of-record for an XDR record. Format #include bool_t xdrrec_endofrecord (XDR *xdrs, bool_t sendnow); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. sendnow Indicates whether the record should be sent. If sendnow is TRUE, xdrrec_endofrecord sends the record by calling the writeit routine specified in the call to xdrrec_create. If sendnow is FALSE, xdrrec_endofrecord marks the end of the record and calls writeit when the buffer is full. 5 Description This routine lets an application support batch calls and pipelined procedure calls. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdrrec_eof Moves the buffer pointer to the end of the current record and returns an indication if any more data exists in the buffer. Format #include bool_t xdrrec_eof (XDR *xdrs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. 5 Description Returns TRUE if there is no more input in the buffer after consuming the rest of the current record. 5 Return_Values TRUE Indicates no more input in the buffer. FALSE Indicates more input in the buffer. 4 xdrrec_skiprecord Guarantees proper record alignment during deserialization from an incoming stream. Format #include bool_t xdrrec_skiprecord (XDR *xdrs); 5 Arguments xdrs A pointer to an XDR stream handle created by one of the XDR stream-handle creation routines. 5 Description This routine ensures that the stream is properly aligned in preparation for a subsequent read. It is recommended that, when a record stream is being used, this routine be called prior to any operations that would read from the stream. This routine is similar to the xdrrec_eof routine, except that this routine does not verify whether there is more data in the buffer. 5 Return_Values TRUE Indicates success. FALSE Indicates failure. 4 xdrstdio_create Initializes an stdio XDR stream. Format #include void xdrstdio_create (XDR *xdrs, FILE *file, enum xdr_op op); 5 Arguments xdrs A pointer to the XDR stream handle being created. The routine xdrstdio_create fills in xdrs with encoding and decoding information.. file A pointer to the FILE structure that is to be associated with the stream. op An XDR operation, one of: XDR_ENCODE, XDR_DECODE, and XDR_FREE. 5 Description Initializes a stdio stream for the specified file. 5 Return_Values None 3 Socket_API_Functions Socket functions let you write network programs that can be easily ported to other operating systems. 4 accept() Accepts a connection on a passive socket. The $QIO equivalent is the IO$_ACCESS system service with the IO$M_ACCEPT modifier. Format #include #include int accept ( int s, struct sockaddr *addr, int *addrlen ); (_DECC_V4_SOURCE) int accept ( int s, struct sockaddr *addr, size_t *addrlen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor returned by socket(), subsequently bound to an address with bind(), which is listening for connections after a listen(). addr A result argument filled in with the address of the connecting entity, as known to the TCP/IP kernel. The exact format of the structure to which the address parameter points is determined by the address family. Specify either the IPv4 address family (AF_ INET) or the IPv6 address family (AF_INET6). addrlen A value/result argument. It should initially contain the size of the structure pointed to by addr. On return it will contain the actual length, in bytes, of the sockaddr structure that has been filled in by the TCP/IP kernel. 5 Description This function completes the first connection on the queue of pending connections, creates a new socket with the same properties as s, and allocates and returns a new descriptor for the socket. If no pending connections are present on the queue and the socket is not marked as nonblocking, accept() blocks the caller until a connection request is present. If the socket is marked nonblocking by using a setsockopt() call and no pending connections are present on the queue, accept() returns an error. You cannot use the accepted socket to accept subsequent connections. The original socket s remains open (listening) for other connection requests. This call is used with connection- based socket types (SOCK_STREAM). You can select a socket for the purposes of performing an accept by selecting it for a read. Related Functions See also bind(), connect(), listen(), select(), and socket(). 5 Return_Values x A positive integer that is a descriptor for the accepted socket. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. ECONNABORTED A connection has been aborted. EFAULT The addr argument is not in a writable part of the user address space. EINTR The accept() function was interrupted by a signal before a valid connection arrived. EINVAL The socket is not accepting connections. EMFILE There are too many open file descriptors. ENFILE The maximum number of file descriptors in the system is already open. ENETDOWN TCP/IP Services was not started. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system was unable to allocate kernel memory. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The reference socket is not of type SOCK_ STREAM. EPROTO A protocol error occurred. EWOULDBLOCK The socket is marked nonblocking, and no connections are present to be accepted. 4 bind() Binds a name to a socket. The $QIO equivalent is the IO$_SETMODE system service with the p3 argument. Format #include #include int bind ( int s, struct sockaddr *name, int namelen ); (_DECC_V4_SOURCE) int bind ( int s, const struct sockaddr *name, size_t namelen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created with the socket() function. name Address of a structure used to assign a name to the socket in the format specific to the family (AF_INET or AF_INET6) socket address. namelen The size, in bytes, of the structure pointed to by name. 5 Description This function assigns a port number and IP address to an unnamed socket. When a socket is created with the socket() function, it exists in a name space (address family) but has no name assigned. The bind() function requests that a name be assigned to the socket. Related Functions See also connect(), getsockname(), listen(), and socket(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EACCESS The requested address is protected, and the current user has inadequate permission to access it. EADDRINUSE The specified internet address and ports are already in use. EADDRNOTAVAIL The specified address is not available from the local machine. EAFNOSUPPORT The specified address is invalid for the address family of the specified socket. EBADF The socket descriptor is invalid. EDESTADDRREQ The address argument is a null pointer. EFAULT The name argument is not a valid part of the user address space. EINVAL The socket is already bound to an address and the protocol does not support binding to a new address, the socket has been shut down, or the length or the namelen argument is invalid for the address family. EISCONN The socket is already connected. EISDIR The address argument is a null pointer. ENOBUFS The system has insufficient resources to complete the call. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The socket type of the specified socket does not support binding to an address. 4 close() Closes a connection and deletes a socket descriptor. The $QIO equivalent is the $DASSGN system service. Format #include int close ( s ); 5 Argument s A socket descriptor. 5 Description This function deletes a descriptor from the per-process object reference table. Associated TCP connections close first. If a call to connect() fails for a socket in connection mode, applications should use close() to deallocate the socket and descriptor. Related Functions See also accept(), socket(), and write(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. EINTR The close() function was interrupted by a signal that was caught. 4 connect() Initiates a connection on a socket. The $QIO equivalent is the IO$_ACCESS system service. Format #include #include int connect ( int s, struct sockaddr *name, int namelen ); (_DECC_V4_SOURCE) int connect ( int s, const struct sockaddr *name, size_t namelen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created with socket(). name The address of a structure that specifies the name of the remote socket in the format specific to the address family (AF_INET or AF_INET6). namelen The size, in bytes, of the structure pointed to by name. 5 Description This function initiates a connection on a socket. If s is a socket descriptor of type SOCK_DGRAM, then this call permanently specifies the peer where the data is sent. If s is of type SOCK_STREAM, then this call attempts to make a connection to the specified socket. If a call to connect() fails for a connection-mode socket, applications should use close() to deallocate the socket and descriptor. If attempting to reinitiate the connection, applications should create a new socket. Related Functions See also accept(), select(), socket(), getsockname(), and shutdown(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EADDRINUSE Configuration problem. There are insufficient ports available for the attempted connection. The inet subsystem attribute ipport_ userreserved should be increased. EADDRNOTAVAIL The specified address is not available from the local machine. EAFNOSUPPORT The addresses in the specified address family cannot be used with this socket. EALREADY A connection request is already in progress for the specified socket. EBADF The socket descriptor is invalid. ECONNREFUSED The attempt to connect was rejected. EFAULT The name argument is not a valid part of the user address space. EHOSTUNREACH The specified host is not reachable. EINPROGRESS O_NONBLOCK is set for the file descriptor for the socket, and the connection cannot be immediately established; the connection will be established asynchronously. EINTR The connect() function was interrupted by a signal while waiting for the connection to be established. Once established, the connection may continue asynchronously. EINVAL The value of the namelen argument is invalid for the specified address family, or the sa_ family member in the socket address structure is invalid for the protocol. EISCONN The socket is already connected. ELOOP Too many symbolic links were encountered in translating the file specification in the address. ENETDOWN The local network connection is not operational. ENETUNREACH No route to the network or host is present. ENOBUFS The system has insufficient resources to complete the call. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The socket is listening and cannot be connected. EPROTOTYPE The specified address has a different type than the socket bound to the specified peer address. ETIMEDOUT The connection request timed out without establishing a connection. EWOULDBLOCK The socket is nonblocking, and the connection cannot be completed immediately. It is possible to use the select() function to select the socket for writing. 4 decc$get_sdc() Returns the socket device's OpenVMS I/O channel (SDC) associated with a socket descriptor. Format #include short int decc$get_sdc ( int s ); 5 Argument s A socket descriptor. 5 Description This function returns the SDC associated with a socket. Normally, socket descriptors are used either as file descriptors or with one of the functions that takes an explicit socket descriptor as its argument. Sockets are implemented using TCP/IP device sockets. This function returns the SDC used by a given socket descriptor so you can directly access the TCP/IP facilities by means of $QIO system services. 5 Return_Values 0 Indicates that s is not an open socket descriptor. x The SDC number. 4 decc$socket_fd Returns the socket descriptor associated with a Socket Device Channel (SDC) for direct use with the OpenVMS C Run-Time Library. Format #include int decc$socket_fd (int channel); 5 Argument channel A valid SDC. 5 Description This function associates a valid socket channel with an HP C run-time library file descriptor, and returns the file descriptor. The file descriptor can then be used with any HP C run-time library function that takes a file descriptor or socket descriptor as an input parameter. 5 Return_Values x The socket descriptor. -1 Indicates an error; the socket descriptor cannot be allocated. 4 endhostent() Closes hosts database file. Format #include void endhostent (void); 5 Description This function closes the hosts database file (TCPIP$ETC:IPNODES.DAT), previously opened with a gethostbyaddr(), gethostent(), or gethostbyname() function call. If the most recent sethostent() function call is executed with a nonzero stay_open parameter, the endhostent() function does not close the hosts database file. You cannot close the hosts database file until you make a call to exit(). A second call to sethostent() is issued with a stay_open parameter equal to 0 (zero). This ensures that a subsequent endhostent() call succeeds. Related Functions See also gethostbyaddr(), gethostent(), and gethostbyname(). 4 endnetent() Closes the networks database file. Format #include void endnetent (void); 5 Description This function closes the networks database file (TCPIP$SYSTEM:NETWORKS.DAT), previously opened with the getnetent(), setnetent(), getnetbyaddr(), or getnetbyname() function. Related Functions See also getnetent(), getnetbyaddr(), getnetbyname(), and setnetent(). 4 endprotoent() Resets the index for the protocols table. Format #include void endprotoent (void); 5 Description This function resets the index for the protocols table previously accessed with a getprotoent(), getprotobyname(), or getprotobynumber() function call. Related Functions See also getprotobyname(), getprotoent(), and getprotobynumber(). 4 endservent() Closes the services database file. Format #include void endservent (void); 5 Description This function closes the services database file (TCPIP$ETC:SERVICES.DAT), previously opened with the getservent(), getservbyname(), or getservbyport() function. Related Functions See also getservent(), getservbyname(), and getservbyport(). 4 freeaddrinfo() Frees system resources used by an address information structure. Format #include void freeaddrinfo ( struct addrinfo *ai ); 5 Arguments ai Points to an addrinfo structure to be freed. The NETDB.H header file defines the addrinfo structure. 5 Description This function frees an addrinfo structure and any dynamic storage pointed to by the structure. The process continues until the function encounters a NULL ai_next pointer. 4 gai_strerror() Provides a descriptive text string that corresponds to an EAI_xxx error value. Format #include const char *gai_strerror ( int ecode ); 5 Arguments ecode The ecode argument is one of the EAI_xxx values defined for the getaddrinfo() and getnameinfo() functions. The values for ecode are: EAI_AGAIN The name could not be resolved at this time. Future attempts may succeed. EAI_BADFLAGS The flags parameter had an invalid value. EAI_FAIL A nonrecoverable error occurred when attempting to resolve the name. EAI_FAMILY The address family was not recognized. EAI_MEMORY There was a memory allocation failure when trying to allocate storage for the return value. EAI_NONAME The name does not resolve for the supplied parameters. Neither nodename nor servname were supplied. At least one of these must be supplied. EAI_SERVICE The service passed was not recognized for the specified socket type. EAI_SOCKTYPE The intended socket type was not recognized. EAI_SYSTEM A system error occurred; the error code can be found in errno. 5 Description This function returns a descriptive text string that corresponds to an EAI_xxx error value. The return value points to a string that describes the error. If the argument is not one of the EAI_ xxx values, the function returns a pointer to a string whose contents indicate an unknown error. For a complete list of error codes, see Error Codes. 5 Return_Values x text string -1 Failure 4 getaddrinfo() Takes a service location (nodename) or a service name (servname), or both, and returns a pointer to a linked list of one or more structures of type addrinfo. Format #include #include int getaddrinfo ( const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res ); 5 Arguments nodename Points to a network node name, alias, or numeric host address (for example, an IPv4 dotted-decimal address or an IPv6 hexadecimal address). An IPv6 nonglobal address with an intended scope zone may also be specified. This is a null-terminated string or NULL. NULL means the service location is local to the caller. The nodename and servname arguments must not both be NULL. servname Points to a network service name or port number. This is a null- terminated string or NULL; NULL returns network-level addresses for the specified nodename. The nodename and servname arguments must not both be NULL. hints Points to an addrinfo structure that contains information about the type of socket, address family, or protocol the caller supports. The NETDB.H header file defines the addrinfo structure. If hints is a null pointer, the behavior is the same as if addrinfo contained the value 0 for the ai_flags, ai_socktype and ai_protocol members and AF_UNSPEC for the ai_family member. res Points to a linked list of one or more addrinfo structures. 5 Description This function takes a service location (nodename) or a service name (servname), or both, and returns a pointer to a linked list of one or more structures of type addrinfo. Its members specify data obtained from the local hosts database TCPIP$ETC:IPNODES.DAT file, the local TCPIP$HOSTS.DAT file, or one of the files distributed by DNS/BIND. The NETDB.H header file defines the addrinfo structure. If the hints argument is non-NULL, all addrinfo structure members other than the following members must be zero or a NULL pointer: o ai_flags Controls the processing behavior of getaddrinfo(). See Member Values for a complete description of the flags. o ai_family Specifies to return addresses for use with a specific protocol family. - If you specify a value of AF_UNSPEC, getaddrinfo() returns addresses for any protocol family that can be used with nodename or servname. - If the value is not AF_UNSPEC and ai_protocol is not zero, getaddrinfo() returns addresses for use only with the specified protocol family and protocol. - If the application handles only IPv4, set this member of the hints structure to PF_INET. o ai_socktype Specifies a socket type for the given service. If you specify a value of 0, you will accept any socket type. This resolves the service name for all socket types and returns all successful results. o ai_protocol Specifies a network protocol. If you specify a value of 0, you will accept any protocol. If the application handles only TCP, set this member to IPPROTO_TCP. Member Values describes the values for ai_flags members. Table 4-1 ai_flags Member Values Flag Value Description AI_V4MAPPED If ai_family is AF_INET, the flag is ignored. If ai_family is AF_INET6, getaddrinfo() searches for AAAA records. The lookup sequence is: 1. Local hosts database 2. TCPIP$ETC:IPNODES.DAT 3. BIND database The lookup for a particular type of record, for example an AAAA record, will be performed in each database before moving on to perform a lookup for the next type of record. o If AAAA records are found, returns IPv6 addresses; no search for A records is performed. o If no AAAA records are found, searches for A records. o If A records found, returns IPv4-mapped IPv6 addresses. o If no A records found, returns a NULL pointer. AI_ALL| If ai_family is AF_INET, the flag is ignored. AI_V4MAPPED If the ai_family is AF_INET6, getaddrinfo() searches for AAAA records. The lookup sequence is: 1. Local hosts database 2. TCPIP$ETC:IPNODES.DAT 3. BIND database The lookup for a particular type of record, for example an AAAA record, will be performed in each database before moving on to perform a lookup for the next type of record. o If AAAA records are found, IPv6 addresses will be included with the returned addresses. o If A records are found, returns IPv4-mapped IPv6 addresses and also any IPv6 addresses that were found with the AAAA record search. o If no A records found, returns a NULL pointer. AI_CANONNAME If the nodename argument is not NULL, the function searches for the specified node's canonical name. Upon successful completion, the ai_canonname member of the first addrinfo structure in the linked list points to a null-terminated string containing the canonical name of the specified node name. If the nodename argument is an address literal, the ai_cannonname member will refer to the nodename argument that has been converted to its numeric binary form, in network byte order. If the canonical name is not available, the ai_ canonname member refers to the nodename argument or to a string with the same contents. The ai_flags field contents are undefined. AI_NUMERICHOST A non-NULL node name string must be a numeric host address string. Resolution of the service name is not performed. AI_NUMERICSERV A non-NULL service name string must be a numeric port string. Resolution of the service name is not performed. AI_PASSIVE Returns a socket address structure that your application can use in a call to bind(). If the nodename parameter is a NULL pointer, the IP address portion of the socket address structure is set to INADDR_ANY (for an IPv4 address) or IN6ADDR_ANY_INIT (for an IPv6 address). If not set, returns a socket address structure that your application can use to call connect() (for a connection-oriented protocol) or either connect(), sendto(), or sendmsg() (for a connectionless protocol). If the nodename argument is a NULL pointer, the IP address portion of the socket address structure is set to the loopback address. AI_ADDRCONFIG Used in combination with other flags, modifies the search based on the source address or addresses configured on the system. You can use the flags in any combination to achieve finer control of the translation process. Many applications use the combination of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their search. o If the value of ai_family is AF_INET, and an IPv4 source address is configured on the system, getaddrinfo() searches for A records only. If found, getaddrinfo() returns IPv4 addresses. If not, getaddrinfo() returns a NULL pointer. o If the value of ai_family is AF_INET6 and an IPv6 source address is configured on the system, getaddrinfo() searches for AAAA records. If found, getaddrinfo() returns IPv6 addresses. If not, and if an IPv4 address is configured on the system, getaddrinfo() searches for A records. If found, getaddrinfo() returns IPv4-mapped IPv6 addresses. If not, getaddrinfo() returns a NULL pointer. These flags are defined in the NETDB.H header file. addrinfo Structure Processing Upon successful return, getaddrinfo() returns a pointer to a linked list of one or more addrinfo structures. The application can process each addrinfo structure in the list by following the ai_next pointer until a NULL pointer is encountered. In each returned addrinfo structure, the ai_family, ai_socktype, and ai_ protocol members are the corresponding arguments for a call to the socket() function. The ai_addr member points to a filled-in socket address structure whose length is specified by the ai_ addrlen member. 5 Return_Values 0 Indicates success -1 Indicates an error 5 Errors EAI_AGAIN The name could not be resolved at this time. Future attempts may succeed. EAI_BADFLAGS The flags parameter had an invalid value. EAI_FAIL A nonrecoverable error occurred when attempting to resolve the name. EAI_FAMILY The address family was not recognized. EAI_MEMORY There was a memory allocation failure when trying to allocate storage for the return value. EAI_NONAME The name does not resolve for the supplied parameters. Neither nodename nor servname were supplied. At least one of these must be supplied. EAI_SERVICE The service passed was not recognized for the specified socket type. EAI_SOCKTYPE The intended socket type was not recognized. EAI_SYSTEM A system error occurred; the error code can be found in errno. 4 gethostaddr Returns the standard host address for the processor. Format #include int gethostaddr (char *addr); 5 Argument addr A pointer to the buffer in which the standard host address for the current processor is returned. 5 Description This function returns the standard host address for the current processor. The returned address is null-terminated. The addr parameter must point to at least 16 bytes of free space. Host addresses are limited to 16 characters. 5 Return_Values 0 Indicates success. -1 Indicates that an error has occurred and is further specified in the global errno. 4 gethostbyaddr() Searches the hosts database that is referenced by the TCPIP$HOST logical name for a host record with a given IPv4 address. If the host record is not found there, the function may also invoke the BIND resolver to query the appropriate name server. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYADDR subfunction code. Format #include struct hostent *gethostbyaddr ( const void *addr, size_t len, int type ); 5 Arguments addr A pointer to a series of bytes in network order specifying the address of the host sought. len The number of bytes in the address pointed to by the addr argument. type The type of address format being sought (AF_INET). 5 Description This function finds the first host record with the specified address in the hosts database or using DNS/BIND. The gethostbyaddr() function uses a common static area for its return values. This means that subsequent calls to this function overwrite previously returned host entries. You must make a copy of the host entry if you want to save it. 5 Return_Values x A pointer to an object having the hostent structure. NULL Indicates an error; errno is set to one of the following values. 5 Errors ENETDOWN TCP/IP Services was not started. HOST_NOT_FOUND Host is unknown. NO_DATA The server recognized the request and the name, but no address is available for the name. Another type of name server request may be successful. NO_RECOVERY An unexpected server failure occurred. This is a nonrecoverable error. TRY_AGAIN A transient error occurred; for example, the server did not respond. A retry may be successful. 4 gethostbyname() Searches the hosts database that is referenced by the TCPIP$HOST logical name for a host record with the specified name or alias. If the host record is not found, this function may also invoke the BIND resolver to query the appropriate name server for the information. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYNAME subfunction code. Format #include struct hostent *gethostbyname ( char *name ); 5 Argument name A pointer to a null-terminated character string containing the name or an alias of the host being sought. 5 Description This function finds the first host with the specified name or alias in the hosts database, or using DNS/BIND. The gethostbyname() function uses a common static area for its return values. This means that subsequent calls to this function overwrite previously returned host entries. You must make a copy of the host entry if you want to save it. 5 Return_Values x A pointer to an object having the hostent structure. NULL Indicates an error. errno is set to one of the following values. 5 Errors ENETDOWN TCP/IP Services was not started. HOST_NOT_FOUND Host is unknown. NO_DATA The server recognized the request and the name, but no address is available for the name. Another type of name server request may be successful. NO_RECOVERY An unexpected server failure occurred. This is a nonrecoverable error. TRY_AGAIN A transient error occurred; for example, the server did not respond. A retry may be successful. 4 gethostent() Retrieves an entry from the hosts database file. Format #include struct hostent *gethostent (void); 5 Description The gethostent() function reads the next entry of the hosts database file (TCPIP$ETC:IPNODES.DAT). See the NETDB.H header file for a description of the hostent structure. The gethostent() function uses a common static area for its return values. Therefore, subsequent calls to gethostent() overwrite any existing host entry. You must make a copy of the host entry, if you wish to save it. 5 Return_Values x A pointer to an object having the hostent structure. NULL Indicates an error; errno is set to one of the following values. 5 Errors ENETDOWN TCP/IP Services was not started. HOST_NOT_FOUND Host is unknown. NO_DATA The server recognized the request and the name, but no address is available for the name. Another type of name server request may be successful. NO_RECOVERY An unexpected server failure occurred. This is a nonrecoverable error. TRY_AGAIN A transient error occurred; for example, the server did not respond. A retry may be successful. 4 gethostname() Returns the fully-qualified name of the local host. Format #include #include int gethostname ( char *name, int namelen) ; (_DECC_V4_SOURCE) int gethostname ( char *name, size_t namelen) ; (not_DECC_V4_SOURCE) 5 Arguments name The address of a buffer where the name should be returned. The returned name is null terminated unless sufficient space is not provided. namelen The size of the buffer pointed to by name. 5 Description This function returns the translation of the logical names TCPIP$INET_HOST and TCPIP$INET_DOMAIN when used with the TCP/IP Services software. 5 Return_Values 0 Indicates successful completion. -1 Indicates an error occurred. The value of errno indicates the error. 5 Errors EFAULT The buffer described by name and namelen is not a valid, writable part of the user address space. 4 getnameinfo() Maps addresses to names in a protocol-independent way. Format #include #include int getnameinfo ( const struct sockaddr *sa, size_t salen, char *node, size_t nodelen, char *service, size_t servicelen, int flags ); 5 Arguments sa Points either to a sockaddr_in structure (for IPv4) or to a sockaddr_in6 structure (for IPv6) that holds the IP address and port number. salen Specifies the length of either the sockaddr_in structure or the sockaddr_in6 structure. node Points to a buffer in which to receive the null-terminated network node name or alias corresponding to the address contained in the sa. A NULL pointer instructs getnameinfo() to not return a node name. The node argument and service argument must not both be zero. nodelen Specifies the length of the node buffer. A value of zero instructs getnameinfo() to not return a node name. service Points to a buffer in which to receive the null-terminated network service name associated with the port number contained in sa. A NULL pointer instructs getnameinfo() to not return a service name. The node argument and service argument must not both be 0. servicelen Specifies the length of the service buffer. A value of zero instructs getnameinfo() to not return a service name. flags Specifies changes to the default actions of getnameinfo(). By default, getnameinfo() searches for the fully-qualified domain name of the node in the hosts database and returns it. See Flags for a list of flags and their meanings. 5 Description This function looks up an IP address and port number in a sockaddr structure specified by sa and returns node name and service name text strings in the buffers pointed to by the node and service arguments, respectively. If the node name is not found, getnameinfo() returns the numeric form of the node address, regardless of the value of the flags argument. If the service name is not found, getnameinfo() returns the numeric form of the service address (port number) regardless of the value of the flags argument. The application must provide buffers large enough to hold the fully-qualified domain name and the service name, including the terminating null characters. Flags describes the flag bits and, if set, their meanings. The flags are defined in the NETDB.H header file. Table 4-2 getnameinfo() Flags Flag Value Description NI_DGRAM Specifies that the service is a datagram service (SOCK_DGRAM). The default assumes a stream service (SOCK_STREAM). This is required for the few ports (512-514) that have different services for UDP and TCP. NI_NAMEREQD Returns an error if the host name cannot be located in the hosts database. NI_NOFQDN Searches the hosts database and returns the node name portion of the fully-qualified domain name for local hosts. NI_NUMERICHOST Returns the numeric form of the host's address instead of its name. Resolution of the host name is not performed. NI_NUMERICSERV Returns the numeric form (port number) of the service address instead of its name. The host name is not resolved. 5 Return_Values 0 Indicates success. x Indicates an error occurred. The value of errno indicates the error. 5 Errors EAI_AGAIN The name could not be resolved at this time. Future attempts may succeed. EAI_BADFLAGS The flags argument had an invalid value. EAI_FAIL A nonrecoverable error occurred when attempting to resolve the name. EAI_FAMILY The address family was not recognized. EAI_MEMORY There was a memory allocation failure when trying to allocate storage for the return value. EAI_NONAME The name does not resolve for the supplied parameters. Neither the node name nor the service name were supplied. At least one of these must be supplied. EAI_SYSTEM A system error occurred; the error code can be found in errno. 4 getnetbyaddr() Searches the network database that is referenced by the TCPIP$NETWORK logical name for a network record with the specified address. If the network record is not found, this function may invoke the BIND resolver to search TCPIP$SYSTEM:NETWORKS.DAT. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYADDR subfunction code. Format #include struct netent *getnetbyaddr ( long net, int type) ; 5 Arguments net The network number, in host byte order, of the networks database entry required. type The type of network being sought (AF_INET or AF_INET6). 5 Description This function finds the first network record in the networks database with the given address. The getnetbyaddr() and getnetbyname() functions use a common static area for their return values. Subsequent calls to any of these functions overwrite any previously returned network entry. You must make a copy of the network entry if you want to save it. 5 Return_Values x A pointer to an object having the netent structure. NULL Indicates end of file or an error. 5 Errors EINVAL The net argument is invalid. ESRCH The search failed. 4 getnetbyname() Searches the networks database for a network record with a specified name or alias. If the network record is not found, this function may invoke the BIND resolver to search TCPIP$SYSTEM:NETWORKS.DAT. The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYNAME subfunction code. Format #include struct netent *getnetbyname ( char *name ); 5 Argument name A pointer to a null-terminated character string containing either the network name or an alias for the network name. 5 Description This function finds the first network record in the networks database with the given name or alias. The getnetbyaddr() and getnetbyname() functions use a common static area for their return values. Subsequent calls to any of these functions overwrite previously returned network entries. You must make a copy of the network entry if you want to save it. 5 Return_Values NULL Indicates end of file or an error. x A pointer to an object having the netent structure. 5 Errors EFAULT The buffer described by name is not a valid, writable part of the user address space. EINVAL The name argument is invalid. ESRCH The search failed. 4 getnetent() Retrieves an entry from the networks database file. Format #include struct netent *getnetnet (void); 5 Description This function opens and sequentially reads the networks database file (TCPIP$SYSTEM:NETWORKS.DAT) to retrieve network information. Returns a pointer to a netent structure that contains the equivalent fields for a network description line in the networks database file. The netent structure is defined in the NETDB.H header file. The networks database file remains open after a call by the getservent() function. Use the endnetent() function to close the networks database file. Use the setnetent() function to open the networks database file and reset the file marker to the beginning of the file. The getnetent() function uses a common static area for its return values, so subsequent calls to this function overwrite any existing network entry. To save the network entry, you must make a copy of it. Related Functions See also setnetent and endnetent. 5 Return_Values x A pointer to a netent structure. 0 Indicates an error or end of file. 4 getpeername() Returns the name of the connected peer. The $QIO equivalent is the IO$_SENSEMODE function with the p4 argument. Format #include #include int getpeername ( int s, struct sockaddr *name, int *namelen ); (_DECC_V4_SOURCE) int getpeername ( int s, struct sockaddr *name, size_t *namelen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created using socket(). name A pointer to a buffer where the peer name is to be returned. namelen An address of an integer that specifies the size of the name buffer. On return, it is modified to reflect the actual length, in bytes, of the name returned. 5 Description This function returns the name of the peer connected to the specified socket descriptor. Related Functions See also bind(), socket(), and getsockname(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The descriptor is invalid. EFAULT The name argument is not a valid part of the user address space. EINVAL The socket has been shut down. ENOBUFS The system has insufficient resources to complete the call. ENOTCONN The socket is not connected. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The operation is not supported for the socket protocol. 4 getprotobyname() Searches the protocols table until a matching protocol name is found or until the end of the table is encountered. Format #include struct protoent *getprotobyname ( char *name ); 5 Argument name A pointer to a string containing the desired protocol name. 5 Description This function returns a pointer to a protoent structure containing data from the protocols table. For information about the protoent structure, refer to protoent Structure. All information is contained in a static area, so it must be copied to be saved. Related Functions See also getprotoent() and getprotobynumber(). 5 Return_Values NULL Indicates the end of the table or an error. x A pointer to a protoent structure. 4 getprotobynumber() Searches the protocols table until a matching protocol number is found or until the end of the table is encountered. Format #include struct protoent *getprotobynumber ( int *proto ) ; 5 Argument proto A pointer to a string containing the desired protocol number. 5 Description This function returns a pointer to a protoent structure containing the data from the protocols table. For information about the protoent structure, refer to protoent Structure. All information is contained in a static area, so it must be copied to be saved. Related Functions See also getprotoent() and getprotobyname(). 5 Return_Values NULL Indicates end of table or an error. x A pointer to a protoent structure. 4 getprotoent() Reads the next entry from the protocols table. Format #include struct protoent *getprotoent(); 5 Description This function returns a pointer to a protoent structure containing the data from the protocols table. For information about the protoent structure, refer to protoent Structure. The getprotoent() function keeps an index to the table, allowing successive calls to be used to search the entire table. All information is contained in a static area, so it must be copied to be saved. Related Functions See also getprotobyname() and getprotobynumber(). 5 Return_Values NULL Indicates the end of the table or an error. x A pointer to a protoent structure. 4 getservbyname() Gets information on the specified service from the services database that is referenced by the TCPIP$SERVICE logical name. If not found there, this function may invoke the BIND resolver to search TCPIP$ETC:SERVICES.DAT. Format #include struct servent *getservbyname ( char *name, char *proto ); 5 Arguments name A pointer to a string containing the name of the service about which information is required. proto A pointer to a string containing the name of the protocol (TCP or UDP) for which to search. 5 Description This function searches the services database until a matching service name is found or the end of file is encountered. If a protocol name is also supplied, searches must also match the protocol. This function returns a pointer to a servent structure containing the data from the network services database. For information about the servent structure, refer to servent Structure. All information is contained in a static area, so it must be copied to be saved. Related Functions See also getservbyport(). 5 Return_Values NULL Indicates end of file or an error. x A pointer to a servent structure. 4 getservbyport() Gets information on the specified port from the services database that is referenced by the TCPIP$SERVICE logical name. If the specified port is not found, this function may invoke the BIND resolver to search TCPIP$ETC:SERVICES.DAT. Format #include struct servent *getservbyport ( int port, char *proto ); 5 Arguments port The port number for which to search. This port number should be specified in network byte order. You can use the htons() function to convert the port number to network byte order. proto A pointer to a string containing the name of the protocol (TCP or UDP) for which to search. 5 Description This function searches the services database until a matching port is found, or until end of file is encountered. If a protocol name is also supplied, searches must also match the protocol. This function returns a pointer to a servent structure containing the broken-out fields of the requested line in the network services database. For information about the servent structure, refer to servent Structure. All information is contained in a static area, so it must be copied to be saved. Related Functions See also getservbyname(). 5 Return_Values NULL Indicates end of file or an error. x A pointer to a servent structure. 5 Errors EPERM Not owner. Indicates that the wrong port number was specified. 4 getservent() Retrieves an entry from the services database file. Format #include struct servent *getservent (void); 5 Description This function reads the next line of the services database file (TCPIP$ETC:SERVICES.DAT). An application program can use the getservent() function to retrieve information about a service (such as the protocol or the ports it uses) from the services database. The getservent() function returns a servent structure that contains information from the services database file. See servent Structure for a description of the servent structure. The servent structure is defined in the NETDB.H header file. The ASCII text services database file remains open after a call by the getservent() function. Use the endservent() function to close the services database file. Use the setservent() function to open the services database file and reset the file marker to the beginning of the file. The getservent function uses a common static area for its return values, so subsequent calls to this function overwrite any existing service entry. To save the services entry, you must make a copy of it. Related Functions See also setservent and endservent. 5 Return_Values x A pointer to a servent structure. NULL Indicates an error or end of file. 4 getsockname() Returns the name associated with a socket. The $QIO equivalent is the IO$_SENSEMODE function with the p3 argument. Format #include #include int getsockname ( int s, struct sockaddr *name, int *namelen ); (_DECC_V4_SOURCE) int getsockname ( int s, struct sockaddr *name, size_t *namelen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created with the socket() function and bound to the socket name with the bind() function. name A pointer to the buffer in which getsockname() should return the socket name. namelen A pointer to an integer containing the size of the buffer pointed to by name. On return, the integer indicates the actual size, in bytes, of the name returned. 5 Description This function returns the current name for the specified socket descriptor. The name is in a format specific to the address family assigned to the socket (AF_INET, or AF_INET6 with BSD 4.4 when _SOCKADDR_LEN is defined). The bind() function, not the getsockname() function, makes the association of the name to the socket. Related Functions See also bind() and socket(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The descriptor is invalid. EFAULT The name argument is not a valid part of the user address space. ENOBUFS The system has insufficient resources to complete the call. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The operation is not supported for this socket's protocol. 4 getsockopt() Returns the options set on a socket. The $QIO equivalent is the IO$_SENSEMODE function. Format #include #include int getsockopt ( int s, int level, int optname, char *optval, int *optlen ); (_DECC_V4_SOURCE) int getsockopt ( int s, int level, int optname, void *optval, size_t *optlen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created by the socket() function. level The protocol level for which the socket options are desired. It can have one of the following values: SOL_SOCKET Get the options at the socket level. p Any protocol number. Get the options for protocol level specified by p. The IPPROTO values are defined in the IN.H header file (for IPv4), or the IN6.H header file (for IPv6). optname Interpreted by the protocol specified in the level. Options at each protocol level are documented with the protocol. For descriptions of the supported socket level options, see the description of setsockopt() in this chapter. optval Points to a buffer in which the value of the specified option should be placed by getsockopt(). optlen Points to an integer containing the size of the buffer pointed to by optval. On return, the integer is modified to indicate the actual size of the option value returned. 5 Description This function gets information on socket options. See the appropriate protocol for information about available options at each protocol level. 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EACCES The calling process does not have appropriate permissions. EBADF The socket descriptor is invalid. EDOM The send and receive timeout values are too large to fit in the timeout fields of the socket structure. EFAULT The address pointed to by the optval argument is not in a valid (writable) part of the process space, or the optlen argument is not in a valid part of the process address space. EINVAL The optval or optlen argument is invalid; or the socket is shut down. ENOBUFS The system has insufficient resources to complete the call. ENOTSOCK The socket descriptor is invalid. ENOPROTOOPT The option is unknown or the protocol is unsupported. EOPNOTSUPP The operation is not supported by the socket protocol. ENOPROTOOPT The option is unknown. ENOTSOCK The socket descriptor is invalid. 4 herror() Writes a message to standard error explaining h_error. Format #include void herror (const char *string); 5 Argument string A user-printable string. 5 Description This function maps the error number in the external variable h_ errno to a locale-dependent error message. 4 hostalias() Searches for host aliases associated with a name. Format #include char *hostalias (const char *name); 5 Argument name Points to the name of the host that you want to retrieve aliases from. 5 Description This function searches for the alias associated with the name argument. The HOSTALIASES logical name can be used to define the name of a file that lists the host aliases, in the form: host alias 5 Return_Values x The host alias. NULL Indicates an error. 4 hstrerror() Returns an error message string. Format #include char *hstrerror (int errnum); 5 Arguments errnum An error number specifying a value of h_errno. 5 Description This function maps the error number specified by the errnum argument to a location-dependent error message string and returns a pointer to the string. The string pointed to by the return value cannot be modified by the program, but could be overwritten by subsequent calls to this function. 5 Return_Values x A pointer to the generated message string. -1 On error, errno might be set, but no return value is reserved to indicate an error. 5 Errors If the hstrerror() function fails, errno is set to EINVAL, indicating the value of the errnum argument is an invalid error number. 4 htonl() Converts longwords from host byte order to network byte order. Format #include unsigned long int htonl ( unsigned long int hostlong ); 5 Argument hostlong A longword in host byte order (OpenVMS systems). 5 Description This function converts 32-bit unsigned integers from host byte order to network byte order. Data bytes transmitted over the network are expected to be in network byte order. Some hosts, like OpenVMS, have an internal data representation format that is different from the network byte order; this is called the host byte order. Network byte order places the byte with the most significant bits at lower addresses, but OpenVMS host byte order places the most significant bits at the highest address. This function can be used to convert IP addresses from host byte order to network byte order. NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Value x A longword in network byte order. 4 htons() Converts short integers from host byte order to network byte order. Format #include unsigned short int htons ( unsigned short int hostshort ); 5 Argument hostshort A short integer in host byte order (OpenVMS systems). All short integers on OpenVMS systems are in host byte order unless otherwise specified. 5 Description This function converts 16-bit unsigned integers from host byte order to network byte order. Data bytes transmitted over the network are expected to be in network byte order. Some hosts, like OpenVMS, have an internal data representation format that is different from the network byte order; this is called the host byte order. Network byte order places the byte with the most significant bits at lower addresses, but OpenVMS host byte order places the most significant bits at the highest address. This function is most often used with ports returned by the getservent() function. To convert port numbers from OpenVMS host byte order to network byte order, use the htons() function. NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Value x A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on OpenVMS systems. 4 if_freenameindex() Frees dynamic memory allocated by if_nameindex() to the array of interface names and indexes Format #include void if_freenameindex ( struct if_nameindex *ptr ); 5 Arguments ptr Points to an array of structures returned by the if_nameindex() function. 5 Description The if_freenameindex() function frees dynamic memory allocated to the array of interface names and indexes that the if_nameindex() function returned. 4 if_indextoname() Maps an interface index to its corresponding name. Format #include char *if_indextoname ( unsigned int ifindex, char *ifname ); 5 Arguments ifindex The interface index. ifname Points to a buffer that is IFNAMSIZ bytes in length. (IFNAMSIZ is defined in the IF.H header file.) If an interface name is found, it is returned in the buffer. 5 Description This function maps an interface index to its corresponding name. 5 Return_Values Interface name If interface name is found, it is returned to the buffer. NULL If no interface name corresponds to the specified index, the function returns NULL and sets errno to ENXIO. 5 Errors ENXIO No interface name corresponds to the specified index. System error A system error. 4 if_nameindex() Returns an array of all interface names and indexes. Format #include struct if_nameindex *if_nameindex ( void ); 5 Description This function dynamically allocates memory for an array of if_nameindex structures, one structure for each interface. A structure with an if_index value of 0 and a NULL if_name value indicates the end of the array. The following if_nameindex structure must also be defined by including the IF.H header file prior to the call to if_ nameindex(): struct if_nameindex { unsigned int if_index; char *if_name; }; To free the memory allocated by this function, use the if_ freenameindex() function. If an error occurs, the function returns a NULL pointer and sets errno to an appropriate value. 5 Return_Values NULL Indicates an error; errno is set to an appropriate value. 4 if_nametoindex() Maps an interface name to its corresponding index. Format #include unsigned int if_nametoindex ( const char *ifname ); 5 Arguments ifname Points to a buffer that contains the interface name. 5 Description This function maps an interface name to its corresponding interface index number. 5 Return_Values 0 (zero) Interface does not exist. x Upon successful conversion, the if_ nametoindex() function returns an interface index number. 4 inet6_opt_append() Returns the length of an IPv6 extension header with a new option and appends the option. Format #include int inet6_opt_append ( void *extbuf, size_t extlen, int offset, uint8_t type, size_t len, uint_t align, void **databufp ); 5 Arguments extbuf Points to a buffer that contains an extension header. This is either a valid pointer or a NULL pointer. extlen Specifies the length of the extension header to initialize. Valid values are 0 if extbuf equals 0, a value returned by inet6_opt_ finish(), or any number that is a multiple of 8. offset Specifies the length of the existing extension header. Obtain this value from a prior call to inet6_opt_init() or inet6_opt_ append(). type Specifies the type of option. Specify a value from 2 to 255, inclusive, excluding 194. len Specifies the length of the option data, excluding the option type and option length fields. Specify a value from 0 to 255, inclusive. align Specifies the alignment of the option. Specify one of the following values: 1, 2, 4, or 8. databufp Points to a buffer that contains the option data. 5 Description This function, when called with extbuf as a NULL pointer and extlen as 0, returns the updated number of bytes in an extension header. If you specify extbuf as a valid pointer and valid extlen and align arguments, the function returns the same information as in the previous case, but also inserts the pad option, initializes the type and len fields, and returns a pointer to the location for the option content. After you call inet6_opt_append(), you can then use the data buffer directly or call inet6_opt_set_val() to specify the option contents. 5 Return_Values x Upon successful completion, the inet6_opt_ append() function returns the updated number of bytes in an extension header. -1 Failure 5 Errors EBADF The socket descriptor is invalid. ECONNABORTED A connection has been aborted. EFAULT The addr argument is not in a writable part of the user address space. EINTR The accept() function was interrupted by a signal before a valid connection arrived. EINVAL The socket is not accepting connections. EMFILE There are too many open file descriptors. ENFILE The maximum number of file descriptors in the system is already open. ENETDOWN TCP/IP Services was not started. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system was unable to allocate kernel memory. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The reference socket is not of type SOCK_ STREAM. EPROTO A protocol error occurred. EWOULDBLOCK The socket is marked nonblocking, and no connections are present to be accepted. 4 inet6_opt_find() Finds a specific option in an extension header. Format #include int inet6_opt_find ( void *extbuf, size_t extlen, int offset, uint8_t type, size_t *lenp, void **databufp ); 5 Arguments extbuf Points to a buffer that contains an extension header. extlen Specifies the length, in bytes, of the extension header. offset Specifies the location in the extension header of an option. Valid values are either 0 (zero) for the first option or the length returned from a previous call to either inet6_opt_next() or inet6_opt_find(). type Specifies the type of option to find. lenp Points to the length of the option found. databufp Points to the option data. 5 Description This function searches a received option extension header for an option specified by type. If it finds the specified option, it returns the option length and a pointer to the option data. It also returns an offset to the next option, which you can specify in the offset argument to subsequent calls to inet6_opt_next() in order to search for additional occurrences of the same option type. 5 Return_Values x Upon successful completion, the inet6_opt_ find() function returns an offset from which you can begin the next search in the data buffer. -1 Failure 4 inet6_opt_finish() Returns the total length of an IPv6 extension header, including padding, and initializes the option. Format #include int inet6_opt_finish ( void *extbuf, size_t extlen, int offset ); 5 Arguments extbuf Points to a buffer that contains an extension header. This is either a valid pointer or a NULL pointer. extlen Specifies the length of the extension header to finish initializing. A valid value is any number greater than or equal to 0. offset Specifies the length of the existing extension header. Obtain this value from a prior call to inet6_opt_init() or inet6_opt_ append(). 5 Description This function, when called with extbuf as a NULL pointer and extlen as 0, returns the total number of bytes in an extension header, including final padding. If you specify extbuf as a valid pointer and a valid extlen argument, the function returns the same information as in the previous case, increments the buffer pointer, and verifies that the buffer is large enough to hold the header. 5 Return_Values x Upon successful completion, the inet6_opt_ finish() function returns the total number of bytes in an extension header, including padding. -1 Failure 4 inet6_opt_get_val() Extracts data items from the data portion of an IPv6 option. Format #include int inet6_opt_get_val ( void *databuf, size_t offset, void *val, int vallen ); 5 Arguments databuf Points to a buffer that contains an extension header. This is a pointer returned by a call to inet6_opt_find() or inet6_opt_ next(). offset Specifies the location in the data portion of the option from which to extract the data. You can access the first byte after the option type and length by specifying the offset of 0. val Points to a destination for the extracted data. vallen Specifies the length of the data, in bytes, to be extracted. 5 Description This function copies data items from data buffer databuf beginning at offset to the location val. In addition, it returns the offset for the next data field to assist you in extracting option content that has multiple fields. Make sure that each field is aligned on its natural boundaries. 5 Return_Values x Upon successful completion, the inet6_opt_get_ val() function returns the offset for the next field in the data buffer. -1 Failure 4 inet6_opt_init() Returns the length of an IPv6 extension header with no options and initializes the header. Format #include int inet6_opt_init ( void *extbuf, size_t extlen ); 5 Arguments extbuf Points to a buffer that contains an extension header. This is either a valid pointer or a NULL pointer. extlen Specifies the length of the extension header to initialize. Valid values are 0 and any number that is a multiple of 8. 5 Description This function, when called with extbuf as a NULL pointer and extlen as 0, returns the number of bytes in an extension header that has no options. If you specify extbuf as a valid pointer and extlen as a number that is a multiple of 8, the function returns the same information as in the previous case, initializes the extension header, and sets the length field. 5 Return_Values x Upon successful completion, the inet6_opt_ init() function returns the number of bytes in an extension header with no options. -1 Failure 4 inet6_opt_next() Parses received option extension headers. Format #include int inet6_opt_next ( void *extbuf, size_t extlen, int offset, uint8_t *typep, size_t *lenp, void **databufp ); 5 Arguments extbuf Points to a buffer that contains an extension header. extlen Specifies the length, in bytes, of the extension header. offset Specifies the location in the extension header of an option. Valid values are either 0 for the first option or the length returned from a previous call to either inet6_opt_next() or inet6_opt_find(). typep Points to the type of the option found. lenp Points to the length of the option found. databufp Points to the option data. 5 Description This function parses a received option extension header and returns the next option. In addition, it returns an offset to the next option that you specify in the offset parameter to subsequent calls to inet6_opt_next(). This function does not return any PAD1 or PADN options. 5 Return_Values x Upon successful completion, the inet6_opt_ next() function returns the offset for the next option in the data buffer. -1 Failure 4 inet6_opt_set_val() Adds one component of the option content to the options header. Format #include int inet6_opt_set_val ( void *databuf, size_t offset, void *val int vallen ); 5 Arguments databuf Points to a buffer that contains an extension header. This is a pointer returned by a call to inet6_opt_append(). offset Specifies the location in the data portion of the option into which to insert the data. You can access the first byte after the option type and length by specifying the offset of 0 (zero). val Points to the data to be inserted. vallen Specifies the length of the data, in bytes, to be inserted. 5 Description This function copies data items at the location val into a data buffer databuf beginning at offset. In addition, it returns the offset for the next data field to assist you in composing content that has multiple fields. Make sure that each field is aligned on its natural boundaries. 5 Return_Values x Upon successful completion, the inet6_opt_set_ val() function returns the offset for the next field in the data buffer. -1 Failure 4 inet6_rth_add() Adds an IPv6 address to the routing header under construction. Format #include int inet6_rth_add ( void *bp, const struct in6_addr *addr ); 5 Arguments bp Points to a buffer that is to contain an IPv6 routing header. addr Points to an IPv6 address to add to the routing header. 5 Description This function adds an IPv6 address to the end of the routing header under construction. The address pointed to by addr cannot be an IPv6 V4-mapped address or an IPv6 multicast address. The function increments the ip6r0_segleft member in the ip6_ rthdr0 structure. The ip6_rthdr0 structure is defined in the IP6.H header file. Only routing header type 0 is supported. 5 Return_Values x Upon successful completion, the inet6_rth_ add() function returns 0 (zero). -1 Failure 4 inet6_rth_getaddr() Retrieves an address for an index from an IPv6 routing header. Format #include struct in6_addr *inet6_rth_getaddr ( const void *bp, int index ); 5 Arguments bp Points to a buffer that contains an IPv6 routing header. index Specifies a value that identifies a position in a routing header for a specific address. Valid values range from 0 to the return value from inet6_rth_segments() minus 1. 5 Description This function uses a specified index value and retrieves a pointer to an address in a routing header specified by bp. Call inet6_rth_segments() before calling this function in order to determine the number of segments (addresses) in the routing header. 5 Return_Values x Upon successful completion, the inet6_rth_ getaddr() function returns a pointer to an address. NULL pointer Failure 4 inet6_rth_init() Initializes an IPv6 routing header buffer. Format #include void *inet6_rth_init ( void *bp, int bp_len, int type, int segments ); 5 Arguments bp Points to a buffer that is to contain an IPv6 routing header. bp_len Specifies the length, in bytes, of the buffer. type Specifies the type of routing header. The valid value is IPV6_ RTHDR_TYPE_0 for IPv6 routing header type 0. segments Specifies the number of segments or addresses that are to be included in the routing header. The valid value is from 0 to 127, inclusive. 5 Description This function initializes a buffer and buffer data for an IPv6 routing header. The function sets the ip6r0_segleft, ip6r0_nxt, and ip6r0_reserved members in the ip6_rthdr0 structure to zero. In addition, it sets the ip6r0_type member to type and sets the ip6r0_len member based on the segments argument. The ip6_rthdr0 structure is defined in the IP6.H header file. The application must allocate the buffer. Use the inet6_rth_ space() function to determine the buffer size. Use the returned pointer as the first argument to the inet6_rth_ add() function. 5 Return_Values x Upon successful completion, the inet6_rth_ init() function returns a pointer to the buffer that is to contain the routing header. NULL pointer Failure. If the type is not supported, the bp is a null, or the number of bp_len is invalid. 4 inet6_rth_reverse() Reverses the order of addresses in an IPv6 routing header. Format #include int inet6_rth_reverse ( const void *in, void *out ); 5 Arguments in Points to a buffer that contains an IPv6 routing header. out Points to a buffer that is to contain the routing header with the reversed addresses. This parameter can point to the same buffer specified by the in parameter. 5 Description This function reads an IPv6 routing header and writes a new routing header, reversing the order of addresses in the new header. The in and out parameters can point to the same buffer. The function sets the ip6r0_segleft member in the ip6_rthdr0 structure to the number of segments (addresses) in the new header. The ip6_rthdr0 structure is defined in the IP6.H header file. 5 Return_Values 0 (zero) Success -1 Failure 4 inet6_rth_segments() Returns the number of segments (addresses) in an IPv6 routing header. Format #include int inet6_rth_segments ( const void *bp ); 5 Arguments bp Points to a buffer that contains an IPv6 routing header. 5 Description This function returns the number of segments (or addresses) in an IPv6 routing header. 5 Return_Values x Upon successful completion, the inet6_rth_ segments() function returns the number of segments, 0 (zero) or greater than 0. -1 Failure 4 inet6_rth_space() Returns the number of bytes required for an IPv6 routing header. Format #include size_t inet6_rth_space ( int type, int segments ); 5 Arguments type Specifies the type of routing header. The valid value is IPV6_ RTHDR_TYPE_0 for IPv6 routing header type 0. segments Specifies the number of segments or addresses that are to be included in the routing header. The valid value is from 0 to 127, inclusive. 5 Description This function determines the amount of space, in bytes, required for a routing header. Although the function returns the amount of space required, it does not allocate buffer space. This enables the application to allocate a larger buffer. If the application uses ancillary data, it must pass the returned length to CMSG_LEN() to determine the amount of memory required for the ancillary data object, including the cmsghdr structure. NOTE If an application wants to send other ancillary data objects, it must specify them to sendmsg() as a single msg_ control buffer. 5 Return_Values x Upon successful completion, the inet6_rth_ space() function returns the length, in bytes, of the routing header and the specified number of segments. 0 (zero) Failure, if the type is not supported or the number of segments is invalid for the type of routing header. 4 inet_aton() Converts an IP address in the standard dotted-decimal format to its numeric binary form, in network byte order. Replaces the inet_addr() function. Format #include int inet_aton ( const char *cp, struct in_addr *in); 5 Argument cp A pointer to a null-terminated character string containing an internet address in the standard internet dotted-decimal format. in A pointer to a buffer that is to contain the numeric internet address in network byte order. 5 Description This function returns a numeric internet address in network byte order that represents the internet address supplied in standard dotted-decimal format as its argument. Internet addresses specified with the dotted-decimal format take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the 4 bytes of an internet address. Note that when an internet address is viewed as a 32-bit integer quantity on an OpenVMS system, the bytes appear in binary as d.c.b.a. That is, OpenVMS bytes are ordered from least significant to most significant. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as parts in a dotted-decimal address can be decimal, octal, or hexadecimal, as specified in the C language. (That is, a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal.) NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Value 1 Indicates success. 0 Indicates failure. 4 inet_lnaof() Returns the local network address portion of an IP address. Format #include #include int inet_lnaof ( struct in_addr in ); 5 Argument in An IP address. 5 Description This function returns the local network address portion of a full IP address. NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Value x The local network address portion of an IP address, in host byte order. 4 inet_makeaddr() Returns an IP address based on a particular local address and a network. Format #include #include struct in_addr inet_makeaddr ( int net, int lna ); 5 Arguments net An IP network address in host byte order. lna A local network address on network net in host byte order. 5 Description This function combines the net and lna arguments into a single IP address. NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Value x An IP address in network byte order. 4 inet_netof() Returns the internet network address portion of an IP address. Format #include #include int inet_netof ( struct in_addr in ); 5 Argument in An IP address. 5 Description This function returns the internet network address (NET) portion of a full IP address. NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Value x The internet network portion of an IP address, in host byte order. 4 inet_network() Converts a null-terminated text string representing an IP address into a network address in local host format. Format #include #include int inet_network ( const char *cp ); 5 Argument cp A pointer to an ASCII (null-terminated) character string containing a network address in the dotted-decimal format. 5 Description This function returns an internet network address as a local host integer value when an ASCII string representing the address in the internet standard dotted-decimal format is given as its argument. NOTE The 64-bit return from OpenVMS Alpha and I64 systems has zero-extended bits in the high 32 bits of R0. 5 Return_Values -1 Indicates that cp does not point to a proper internet network address. x An internet network address, in local host order. 4 inet_ntoa() Converts an IP address into a text string representing the address in the standard internet dotted-decimal format. Format #include #include char *inet_ntoa ( struct in_addr in ); 5 Argument in An IP address in network byte order. 5 Description This function converts an IP address into an ASCII (null- terminated) string that represents the address in standard internet dotted-decimal format. The string is returned in a static buffer that is overwritten by subsequent calls to inet_ntoa(). If you want to save the text string, you should copy it. 5 Return_Value x A pointer to a string containing the IP address in dotted-decimal format. 4 inet_ntop() Converts a numeric address to a text string suitable for presentation. Format #include const char *inet_ntop ( int af, const void *src, char *dst, size_t size ); 5 Arguments af Specifies the address family. Valid values are AF_INET for an IPv4 address and AF_INET6 for an IPv6 address. src Points to a buffer that contains the numeric IP address. dst Points to a buffer that is to contain the text string. size Specifies the size of the buffer pointed to by the dst parameter. For IPv4 addresses, the minimum buffer size is 16 bytes. For IPv6 addresses, the minimum buffer size is 46 bytes. INET_ADDRSTRLEN constants are defined in the IN.H header file. INET6_ADDRSTRLEN constants are defined in IN6.H. 5 Description This function converts a numeric IP address value to a text string. 5 Return_Values Pointer to the Success buffer containing the text string Pointer to the Failure buffer containing NULL 4 inet_pton() Converts an address in its standard text presentation form into its numeric binary form, in network byte order. Format #include int inet_pton ( int af, const char *src, void *dst ); 5 Arguments af Specifies the address family. Valid values are AF_INET for an IPv4 address and AF_INET6 for an IPv6 address. src Points to the address text string to be converted. dst Points to a buffer that is to contain the numeric address. 5 Description This function converts a text string to a numeric value in network byte order. o If the af parameter is AF_INET, the function accepts a string in the standard IPv4 dotted-decimal format: ddd.ddd.ddd.ddd In this format, ddd is a one- to three-digit decimal number between 0 and 255. o If the af parameter is AF_INET6, the function accepts a string in the following format: x:x:x:x:x:x:x:x In this format, x is the hexadecimal value of a 16-bit piece of the address. IPv6 addresses can contain long strings of zero (0) bits. To make it easier to write these addresses, you can use double- colon characters (::) one time in an address to represent 1 or more 16-bit groups of zeros. o For mixed IPv4 and IPv6 environments, the following format is also accepted: x:x:x:x:x:x:ddd.ddd.ddd.ddd In this format, x is the hexadecimal value of a 16-bit piece of the address, and ddd is a one- to three-digit decimal value between 0 and 255 that represents the IPv4 address. The calling application is responsible for ensuring that the buffer referred to by the dst parameter is large enough to hold the numeric address. AF_INET addresses require 4 bytes and AF_ INET6 addresses require 16 bytes. 5 Return_Values 1 Indicates success. 0 Indicates that the input string is neither a valid IPv4 dotted-decimal string nor a valid IPv6 address string. -1 Indicates a failure. errno is set to the following value. 5 Errors EAFNOSUPPORT The address family specified in the af parameter is unknown. 4 ioctl() Controls I/O requests to obtain network information. Format #include int ioctl ( int s, int request, ... /* arg */ ); 5 Argument s Specifies the socket descriptor of the requested network device. request Specifies the type of ioctl command to be performed on the device. The request types are grouped as follows: o Socket operations o File operations o Interface operations o ARP cache operations o Routing table operations Refer to IOCTL Requests for a complete list of supported IOCTL commands. arg Specifies arguments for this request. The type of arg is dependent on the specific ioctl() request and device to which the ioctl() call is targeted. 5 Description This function performs a variety of device-specific functions. The request and arg arguments are passed to the file designated by the s argument and then interpreted by the device driver. The basic I/O functions are performed through the read() and write() functions. Encoded in an ioctl() request is whether the argument is an "in" argument or an "out" argument, and the size of the arg argument in bytes. The macros and definitions used to specify an ioctl() request are located in the IOCTL.H header file. 5 Return_Values -1 Error; errno is set to indicate the error. 5 Errors EBADF The s argument is not a valid socket descriptor. EINTR A signal was caught during the ioctl() operation. If an underlying device driver detects an error, errno might be set to one of the following values: EINVAL Either the request or the arg argument is not valid. ENOTTY Reserved for HP use. The s argument is not associated with a network device, or the specified request does not apply to the specific network device. ENXIO The request and arg arguments are valid for this device driver, but the service requested cannot be performed on the device. 4 listen() Converts an unconnected socket into a passive socket and indicates that the TCP/IP kernel should accept incoming connection requests directed to the socket. The $QIO equivalent is the IO$_SETMODE service. Format int listen ( int s, int backlog ); 5 Arguments s A socket descriptor of type SOCK_STREAM created using the socket() function. backlog The maximum number of pending connections that can be queued on the socket at any given time. The maximum number of pending connections can be set by specifying the value of the socket subsystem attribute somaxconn. (Refer to the HP TCP/IP Services for OpenVMS Tuning and Troubleshooting guide for more information.) The default value for the maximum number of pending connections is 1024. 5 Description This function creates a queue for pending connection requests on socket s with a maximum size equal to the value of backlog. Connections can then be accepted with the accept() function. If a connection request arrives with the queue full (that is, more connections pending than specified by the backlog argument), the request is ignored so that TCP retries can succeed. If the backlog has not cleared by the time TCP times out, the connect() function fails with an errno indication of ETIMEDOUT. Related Functions See also accept(), connect(), and socket(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. EDESTADDRREQ The socket is not bound to a local address, and the protocol does not support listening on an unbound socket. EINVAL The socket is already connected, or the socket is shut down. ENOBUFS The system has insufficient resources to complete the call. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The referenced socket is not of a type that supports the operation listen(). 4 ntohl() Converts longwords from network byte order to host byte order. Format #include unsigned long ntohl ( unsigned long netlong ); 5 Argument netlong A longword in network byte order. Integers in network byte order cannot be used for arithmetic computation on OpenVMS systems. 5 Description This function converts 32-bit unsigned integers from network byte order to host byte order. Data bytes transmitted over the network are expected to be in network byte order. Some hosts, like OpenVMS, have an internal data representation format that is different from the network byte order; this is called the host byte order. Network byte order places the byte with the most significant bits at lower addresses, but OpenVMS host byte order places the most significant bits at the highest address. This function can be used to convert IP addresses from network byte order to host byte order. 5 Return_Value x A longword in host byte order. 4 ntohs() Converts short integers from network byte order to host byte order. Format #include unsigned short ntohs ( unsigned short netshort ); 5 Argument netshort A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on OpenVMS systems. 5 Description This function converts 16-bit unsigned integers from network byte order to host byte order. Data bytes transmitted over the network are expected to be in network byte order. Some hosts, like OpenVMS, have an internal data representation format that is different from the network byte order; this is called the host byte order. Network byte order places the byte with the most significant bits at lower addresses, but OpenVMS host byte order places the most significant bits at the highest address. This function can be used to convert port numbers returned by getservent() from network byte order to host byte order. 5 Return_Value x A short integer in host byte order (OpenVMS systems). 4 poll() Monitors conditions on multiple file descriptors. Format #include int poll (struct pollfd fds[], nfds_t nfds, int timeout); 5 Arguments fds An array of pollfd structures, one for each file descriptor of interest. Each pollfd structure includes the following members: int fd The file descriptor int events The requested conditions int revents The reported conditions nfds The number of pollfd structures in the fds array. timeout The maximum length of time (in milliseconds) to wait for one of the specified events to occur. 5 Description This function provides applications with a mechanism for multiplexing input/output over a set of file descriptors. For each member of the array pointed to by fds, poll() examines the given file descriptor for the events specified in events. The number of pollfd structures in the fds array is specified by nfds. The poll() function identifies those file descriptors on which an application can read or write data, or on which certain events have occurred. The fds argument specifies the file descriptors to be examined and the events of interest for each file descriptor. It is a pointer to an array with one member for each open file descriptor of interest. The array's members are pollfd structures within which fd specifies an open file descriptor, and events and revents are bitmasks constructed by OR-ing a combination of the following event flags: o POLLIN Normal data may be received without blocking. o POLLRDNORM Same as POLLIN. o POLLRDBAND Out-of-band data may be received without blocking. o POLLPRI Same as POLLRDBAND o POLLOUT Normal data may be written without blocking. o POLLWRNORM Same as POLLOUT. o POLLWRBAND Out-of-band data may be written without blocking. If the value of fd is less than 0, events is ignored and revents is set to 0 in that entry on return from poll(). In each pollfd structure, poll() clears the revents member except that where the application requested a report on a condition by setting one of the bits of events listed above, poll() sets the corresponding bit in revents if the requested condition is true. If none of the defined events have occurred on any selected file descriptor, poll() waits at least timeout milliseconds for an event to occur on any of the selected file descriptors. If the value of timeout is 0, poll() returns immediately. If the value of timeout is -1, poll() blocks until a specified event occurs or until the call is interrupted. The poll() function is not affected by the O_NONBLOCK flag. On OpenVMS, the poll() function supports sockets only. NOTE HP recommends using the select() function for optimal performance. The poll() function is provided to ease the porting of existing applications from other platforms. 5 Return_Values positive value Upon successful completion, the total number of file descriptors selected (that is, file descriptors for which the revents member is nonzero). 0 Successful completion. The call timed out and no file descriptors were selected. -1 The poll() function failed. The errno is set to indicate the error. 5 Errors EAGAIN The allocation of internal data structures failed but a subsequent request may succeed. EINTR A signal was caught during the poll() function. 4 read() Reads data from a socket or file. The $QIO equivalent is the IO$_READVBLK function. Format #include int read ( int d, void *buffer, int nbytes ); 5 Arguments d A descriptor that must refer to a socket or file currently opened for reading. buffer The address of a user-provided buffer in which the input data is placed. nbytes The maximum number of bytes allowed in the read operation. 5 Description This function reads bytes from a socket or file and places them in a user-defined buffer. If the end of file is not reached, the read() function returns nbytes. If the end of file occurs during the read() function, it returns the number of bytes read. Upon successful completion, read() returns the number of bytes actually read and placed in the buffer. Related Functions See also socket(). 5 Return_Values x The number of bytes read and placed in the buffer. 0 Peer has closed the connection. -1 Error; errno is set to indicate the error. 5 _Errors EBADF The socket descriptor is invalid. ECONNRESET A connection was forcibly closed by a peer. EFAULT The data was specified to be received into a nonexistent or protected part of the process address space. EINTR A signal interrupted the read() function before any data was available. EINVAL The MSG_OOB flag is set and no out-of-band data is available. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system did not have sufficient memory to fulfill the request. ENOTCONN A receive is attempted on a connection- oriented socket that is not connected. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The specified flags are not supported for this socket type or protocol. EWOULDBLOCK The socket is marked nonblocking, and no data is waiting to be received. 4 recv() Receives bytes from a connected socket and places them into a user-provided buffer. The $QIO equivalent is the IO$_READVBLK function. Format #include #include int recv ( int s, char *buf, int len, int flags ); (_DECC_V4_SOURCE) size_t recv ( int s, void *buf, ssize_t len, int flags ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created as the result of a call to accept() or connect(). buf A pointer to a user-provided buffer into which received data will be placed. len The size of the buffer pointed to by buf. flags A bit mask that can contain one or more of the following flags. The mask is built by using a logical OR operation on the appropriate values. Flag Description MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. Use the send(), sendmsg(), and sendto() functions to send out-of-band data. MSG_PEEK Allows you to examine data in the receive buffer without removing it from the system's buffers. 5 Description This function receives data from a connected socket. To receive data on an unconnected socket, use the recvfrom() or recvmsg() functions. The received data is placed in the buffer buf. Data is sent by the socket's peer using the send, sendmsg(), sendto(), or write() functions. Use the select() function to determine when more data arrives. If no data is available at the socket, the recv() call waits for data to arrive, unless the socket is nonblocking. If the socket is nonblocking, a -1 is returned with the external variable errno set to EWOULDBLOCK. Related Functions See also read(), send(), sendmsg(), sendto(), and socket(). 5 Return_Values x The number of bytes received and placed in buf. 0 Peer has closed its send side of the connection. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. ECONNRESET A connection was forcibly closed by a peer. EFAULT The data was specified to be received into a nonexistent or protected part of the process address space. EINTR A signal interrupted the recv() function before any data was available. EINVAL The MSG_OOB flag is set and no out-of-band data is available. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system did not have sufficient memory to fulfill the request. ENOTCONN A receive is attempted on a connection- oriented socket that is not connected. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The specified flags are not supported for this socket type or protocol. EWOULDBLOCK The socket is marked nonblocking, and no data is waiting to be received. 4 recvfrom() Receives bytes for a socket from any source. Format #include #include int recvfrom ( int s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen) ; (_DECC_V4_SOURCE) ssize_t recvfrom ( int s, void *buf, size_t len, int flags, struct sockaddr *from, size_t *fromlen) ; (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created with the socket() function and bound to a name using the bind() function or as a result of the accept() function. buf A pointer to a buffer into which received data is placed. len The size of the buffer pointed to by buf. flags A bit mask that can contain one or more of the following flags. The mask is built by using a logical OR operation on the appropriate values. Flag Description MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. To send out-of-band data, use the send(), sendmsg(), and sendto() functions. MSG_PEEK Allows you to examine the data that is next in line to be received without actually removing it from the system's buffers. from A buffer that the recvfrom() function uses to place the address of the sender who sent the data. If from is non-null, the address is returned. If from is null, the address is not returned. fromlen Points to an integer containing the size of the buffer pointed to by from. On return, the integer is modified to contain the actual length of the socket address structure returned. 5 Description This function allows a named, unconnected socket to receive data. The data is placed in the buffer pointed to by buf, and the address of the sender of the data is placed in the buffer pointed to by from if from is non-null. The structure that from points to is assumed to be as large as the sockaddr structure. To receive bytes from any source, the socket does not need to be connected. You can use the select() function to determine if data is available. If no data is available at the socket, the recvfrom() call waits for data to arrive, unless the socket is nonblocking. If the socket is nonblocking, a -1 is returned with the external variable errno set to EWOULDBLOCK. Related Functions See also read(), send(), sendmsg(), sendto(), and socket(). 5 Return_Values x The number of bytes of data received and placed in buf. 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. ECONNRESET A connection was forcibly closed by a peer. EFAULT A valid message buffer was not specified. Nonexistent or protected address space is specified for the message buffer. EINTR A signal interrupted the recvfrom() function before any data was available. EINVAL The MSG_OOB flag is set, and no out-of-band data is available. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system did not have sufficient memory to fulfill the request. ENOTCONN A receive is attempted on a connection- oriented socket that is not connected. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The specified flags are not supported for this socket type. ETIMEDOUT The connection timed out when trying to establish a connection or when a transmission timed out on an active connection. EWOULDBLOCK The NBIO (nonblocking) flag is set for the socket descriptor and the process delayed during the write operation. 4 recvmsg() Receives bytes on a socket and places them into scattered buffers. Format #include #include int recvmsg ( int s, struct msghdr msg, int flags ); (BSD Version 4.4) int recvmsg ( int s, struct omsghdr msg, int flags ); (BSD Version 4.3) 5 Arguments s A socket descriptor created with the socket() function. msg A pointer to a msghdr structure for receiving the data. flags A bit mask that can contain one or more of the following flags. The mask is built by using a logical OR operation on the appropriate values. Flag Description MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. Use send(), sendmsg(), and sendto() functions to send out-of-band data. MSG_PEEK Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers. 5 Description You can use this function with any socket, whether or not it is in a connected state. It receives data sent by a call to sendmsg(), send(), or sendto(). The message is scattered into several user buffers if such buffers are specified. To receive data, the socket does not need to be connected to another socket. When the ioveciovcnt array specifies more than one buffer, the input data is scattered into iovcnt buffers as specified by the members of the iovec array: iov0, iov1, ..., ioviovcnt When a message is received, it is split among the buffers by filling the first buffer in the list, then the second, and so on, until either all of the buffers are full or there is no more data to be placed in the buffers. You can use the select() function to determine when more data arrives. Related Functions See also read(), send(), and socket(). 5 Return_Values x The number of bytes returned in the msg_iov buffers. 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. ECONNRESET A connection was forcibly closed by a peer. EFAULT The message argument is not in a readable or writable part of user address space. EINTR This function was interrupted by a signal before any data was available. EINVAL The MSG_OOB flag is set, and no out-of-band data is available. The value of the msg_iovlen member of the msghdr structure is less than or equal to zero or is greater than IOV_MAX. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system did not have sufficient memory to fulfill the request. ENOTCONN A receive is attempted on a connection- oriented socket that is not connected. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The specified flags are not supported for this socket type. EWOULDBLOCK The socket is marked nonblocking, and no data is ready to be received. 4 select() Allows you to poll or check a group of sockets for I/O activity. This function indicates which sockets are ready to be read or written, or which sockets have an exception pending. Format #include int select ( int nfds, int *readfds, int *writefds, int *execptfds, struct timeval *timeout ); (_DECC_V4_SOURCE) int select ( int nfds, fd_set *readfds, fd_set *writefds, int *execptfds, struct timeval *timeout ); (not_DECC_V4_SOURCE) 5 Arguments nfds The number of open objects that may be ready for reading or writing or that have exceptions pending. The nfds argument is normally limited to FD_SETSIZE, which is defined in the SOCKET.H header file. Note that a single process can have a maximum of 65535 simultaneous channels (including sockets) on OpenVMS Alpha and I64 systems, and a maximum of 2047 on OpenVMS VAX systems. readfds A pointer to an array of bits, organized as integers, that should be examined for read readiness. If bit n of the longword is set, socket descriptor n is checked to see whether it is ready to be read. All bits set in the bit mask must correspond to the file descriptors of sockets. The select() function cannot be used on normal files. On return, the array to which readfds points contains a bit mask of the sockets that are ready for reading. Only bits that were set on entry to the select() function can be set on exit. writefds A pointer to an array of bits, organized as integers, that should be examined for write readiness. If bit n of the longword is set, socket descriptor n is checked to see whether it is ready to be written to. All bits set in the bit mask must correspond to socket descriptors. On return, the array to which writefds points contains a bit mask of the sockets that are ready for writing. Only bits that were set on entry to the select() function are set on exit. exceptfds A pointer to an array of bits, organized as integers, that is examined for exceptions. If bit n of the longword is set, socket descriptor n is checked to see whether it has any pending exceptions. All bits set in the bit mask must correspond to the file descriptors of sockets. On return, the array exceptfds pointer contains a bit mask of the sockets that have exceptions pending. Only bits that were set on entry to the select() function can be set on exit. timeout The length of time that the select() function should examine the sockets before returning. If one of the sockets specified in the readfds, writefds, and exceptfds bit masks is ready for I/O, the select() function returns before the timeout period expires. The timeout argument points to a timeval structure. 5 Description This function determines the I/O status of the sockets specified in the various mask arguments. It returns when a socket is ready to be read or written, when the timeout period expires, or when exceptions occur. If timeout is a non-null pointer, it specifies a maximum interval to wait for the selection to complete. If the timeout argument is null, the select() function blocks indefinitely until a selected event occurs. To effect a poll, the value for timeout should be non-null, and should point to a zero-value structure. If a process is blocked on a select() function while waiting for input for a socket and the sending process closes the socket, then the select() function notes this as an event and unblocks the process. The descriptors are always modified on return if the select() function returns because of the timeout. NOTE When the socket option SO_OOBINLINE is set on the device socket, the select() function on both read and exception events returns the socket mask that is set on both the read and the exception mask. Otherwise, only the exception mask is set. Related Functions See also accept(), connect(), read(), recv(), recvfrom(), recvmsg(), send(), sendmsg(), sendto(), and write(). 5 Return_Values n The number of sockets ready for I/O or pending exceptions. This value matches the number of returned bits that are set in all output masks. 0 The select() function timed out before any socket became ready for I/O. -1 Error; errno is set to indicate the error. 5 Errors EBADF One or more of the I/O descriptor sets specified an invalid file descriptor. EINTR A signal was delivered before the time limit specified by the timeout argument expired and before any of the selected events occurred. EINVAL The time limit specified by the timeout argument is invalid. The nfds argument is less than zero, or greater than or equal to FD_SETSIZE. EAGAIN Allocation of internal data structures failed. A later call to the select() function may complete successfully. ENETDOWN TCP/IP Services was not started. ENOTSOCK The socket descriptor is invalid. 4 send() Sends bytes through a socket to its connected peer. The $QIO equivalent is the IO$_WRITEVBLK function. Format #include #include int send ( int s, char *msg, int len, int flags ); (_DECC_V4_SOURCE) ssize_t send ( int s, const void *msg, size_t len, int flags ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created with the socket() function that was connected to another socket using the accept() or connect() function. msg A pointer to a buffer containing the data to be sent. len The length, in bytes, of the data pointed to by msg. flags Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent out of band. Data can be received before other pending data on the receiving socket if the receiver also specifies MSG_OOB in the flag argument of its recv() or recvfrom() call. 5 Description This function sends data to a connected peer. You can use this function only on connected sockets. To send data on an unconnected socket, use the sendmsg() or sendto() function. The send() function passes data along to its connected peer, which can receive the data by using the recv() or read() function. Normally the send() function blocks if there is no space for the incoming data in the buffer. It waits until the buffer space becomes available. If the socket is set to nonblocking and there is no space for the data, the send() function fails with the EWOULDBLOCK error. If the message is too large to be sent in one piece, and the socket type is SOCK_DGRAM, which requires that messages be sent in one piece, send() fails with the EMSGSIZE error. If the address specified is an INADDR_BROADCAST address, then the SO_BROADCAST socket option must have been set and the process must have SYSPRV or BYPASS privilege for the I/O operation to succeed. A success return from the send() does not guarantee that the data has been received by the peer. All errors (except EWOULDBLOCK) are detected locally. To determine when it is possible to send more data, use the select() function. Related Functions See also read(), recv(), recvmsg(), recvfrom(), getsockopt(), and socket(). 5 Return_Values n The number of bytes sent. This value normally equals len. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. ECONNRESET A connection was forcibly closed by a peer. EDESTADDRREQ The socket is not connection-oriented, and no peer address is set. EFAULT The message argument is not in a readable or writable part of the user address space. EINTR A signal interrupted the send() before any data was transmitted. EMSGSIZE The message is too large to be sent all at once, as the socket requires. ENETDOWN The local network connection is not operational. ENETUNREACH The destination network is unreachable. ENOBUFS The system has insufficient resources to complete the call. ENOTCONN The socket is not connected or has not had the peer prespecified. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The socket argument is associated with a socket that does not support one or more of the values set in flags. EWOULDBLOCK The socket is marked nonblocking, and no space is available for the send() function. 4 sendmsg() Sends gathered bytes through a socket to any other socket. Format #include #include int sendmsg ( int s, struct msghdr *msg, int flags ); (BSD Version 4.4) int sendmsg ( int s, struct omsghdr *msg, int flags ); (BSD Version 4.3) 5 Arguments s A socket descriptor created with the socket() function. msg A pointer to a msghdr structure containing the message to be sent. The msg_iov field of the msghdr structure is used as a series of buffers from which data is read in order until msg_iovlen bytes have been obtained. flags Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is sent out of band. Data can be received before other pending data on the receiving socket if the receiver specifies a flag of MSG_OOB. 5 Description This function sends the data in a msghdr structure to any other socket. You can use this function on any socket to send data to any named socket. The data in the msg_iov field of the msghdr structure is sent to the socket whose address is specified in the msg_name field of the structure. The receiving socket gets the data using the read(), recv(), recvfrom(), or recvmsg() function. When the iovec array specifies more than one buffer, the data is gathered from all specified buffers before being sent. Normally the sendmsg() function blocks if there is no space for the incoming data in the buffer. It waits until the buffer space becomes available. If the socket is set to nonblocking and there is no space for the data, the sendmsg() function fails with the EWOULDBLOCK error. If the message is too large to be sent in one piece, and the socket type is SOCK_DGRAM, which requires that messages be sent in one piece, sendmsg() fails with the EMSGSIZE error. If the address specified is an INADDR_BROADCAST address, the SO_BROADCAST socket option must be set and the process must have OPER, SYSPRV, or BYPASS privilege for the I/O operation to succeed. A success return from sendmsg() does not guarantee that the data has been received by the peer. All errors (except EWOULDBLOCK) are detected locally. To determine when it is possible to send more data, use the select() function. Related Functions See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt(). 5 Return_Values n The number of bytes sent. -1 Error; errno is set to indicate the error. 5 Errors ENOTSOCK The socket descriptor is invalid. EFAULT An invalid user space address is specified for an argument. EMSGSIZE The socket requires that messages be sent atomically, but the size of the message to be sent makes this impossible. EWOULDBLOCK Blocks if the system does not have enough space for buffering the user data. 4 sendto() Sends bytes through a socket to any other socket. The $QIO equivalent is the IO$_WRITEVBLK function. Format #include #include int sendto ( int s, char *msg, int len, int flags, struct sockaddr *to, int tolen ); (_DECC_V4_SOURCE) ssize_t sendto ( int s, const void *msg, size_t len, int flags, const struct sockaddr *to, size_t tolen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created with the socket() function. msg A pointer to a buffer containing the data to be sent. len The length of the data pointed to by the msg argument. flags Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent out of band. Data can be received before other pending data on the receiving socket if the receiver specifies MSG_OOB in the flag argument of its recv(), recvfrom() or recvmsg() call. to Points to the address structure of the socket to which the data is to be sent. tolen The length of the address pointed to by the to argument. 5 Description This function can be used on sockets to send data to named sockets. The data in the msg buffer is sent to the socket whose address is specified in the to argument, and the address of socket s is provided to the receiving socket. The receiving socket gets the data using the read(), recv(), recvfrom(), or recvmsg() function. Normally the sendto() function blocks if there is no space for the incoming data in the buffer. It waits until the buffer space becomes available. If the socket is set to nonblocking and there is no space for the data, the sendto() function fails with the EWOULDBLOCK error. If the message is too large to be sent in one piece, and the socket type is SOCK_DGRAM, which requires that messages be sent in one piece, sendto() fails with the EMSGSIZE error. If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST socket option must have been set and the process must have SYSPRV or BYPASS privilege for the I/O operation to succeed. A success return from the sendto() does not guarantee that the data has been received by the peer. All errors (except EWOULDBLOCK) are detected locally. To determine when it is possible to send more data, use the select() function. Related Functions See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt(). 5 Return_Values n The number of bytes sent. This value normally equals len. -1 Error; errno is set to indicate the error. 5 Errors EAFNOSUPPORT Addresses in the specified address family cannot be used with this socket. EBADF The socket descriptor is invalid. ECONNRESET A connection was forcibly closed by a peer. EDESTADDRREQ You did not specify a destination address for the connectionless socket and no peer address is set. EFAULT An invalid user space address is specified for an argument. EHOSTUNREACH The destination host is unreachable. EINTR A signal interrupted sendto() before any data was transmitted. EINVAL The tolen argument is not a valid size for the specified address family. EISCONN The connection-oriented socket for which a destination address was specified is already connected. EMSGSIZE The message is too large to be sent all at once, as the socket requires. ENETDOWN The local network connection is not operational. ENETUNREACH The destination network is unreachable. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system did not have sufficient memory to fulfill the request. ENOTCONN The socket is connection-oriented but is not connected. ENOTSOCK The socket descriptor is invalid. EOPNOTSUPP The socket argument is associated with a socket that does not support one or more of the values set in flags. EPIPE The socket is shut down for writing or is connection oriented, and the peer is closed or shut down for reading. In the latter case, if the socket is of type SOCK_STREAM, the SIGPIPE signal is generated to the calling process. EWOULDBLOCK The socket is marked nonblocking, and no space is available for the sendto() function. 4 sethostent() Opens the hosts database file. Format #include void sethostent (int stay_open); 5 Argument stay_open Specifies a value used to indicate when to close the hosts database file (TCPIP$ETC:IPNODES.DAT): o A value of 0 closes the hosts database file after each call to the gethostbyname(), gethostbyaddr(), or gethostent() function. o A nonzero value keeps the hosts database file open after each call. 5 Description This function opens the hosts database file and resets the file marker to the beginning of the file. Passing a nonzero value to the stay_open argument keeps the connection open until the endhostent() or exit() function is called. Related Functions See also endhostent(). 4 setnetent() Opens the networks database file. Format #include void setnetent (int stay_open); 5 Argument stay_open Specifies a value used to indicate when to close the networks database file (TCPIP$SYSTEM:NETWORKS.DAT): o A value of 0 closes the networks database file after each call to the getnetent() function. o A nonzero value keeps the networks database file open after each call. 5 Description This function opens the networks database file and resets the file marker to the beginning of the file. Passing a nonzero stay_open argument keeps the connection open until you call the endnetent() or exit() function. Related Functions See also endnetent(), getnetent(), and exit(). 4 setprotoent() Sets the state of the protocols table. Format #include void setprotoent (int stay_open); 5 Argument stay_open Specifies a value used to indicate when to reset the protocols table index: o A value of 0 resets the protocols table index after each call to the getprotoent function. o A nonzero value does not reset the protocols table index after each call. 5 Description This function sets the index marker to the beginning of the protocols table. Passing a nonzero stay_open argument will allow the index to advance until you call the endprotoent() or exit() function. Related Functions See also endprotoent(), exit(), and getprotoent(). 5 Return_Values 1 Indicates success. 0 Indicates an error; unable to access the protocols table. 4 setservent() Opens the services database file. Format #include void setservent (int stay_open); 5 Argument stay_open Specifies a value used to indicate when to close the services database file (TCPIP$ETC:SERVICES.DAT): o A value of 0 closes the services database file after each call to the setservent() function. o A nonzero value keeps the services database file open after each call to setservent(). 5 Description This function opens the services database file and resets the file marker to the beginning of the file. Passing a nonzero stay_open argument keeps the connection open until you call the endservent() function or the exit() function. Related Functions See also endservent(), exit(), and getservent(). 4 setsockopt() Sets options on a socket. The $QIO equivalent is the IO$_SETMODE function. Format #include #include int setsockopt ( int s, int level, int optname, char *optval, int optlen ); (_DECC_V4_SOURCE) int setsockopt ( int s, int level, int optname, const void *optval, size_t optlen ); (not_DECC_V4_SOURCE) 5 Arguments s A socket descriptor created by the socket() function. level The protocol level for which the socket options are to be modified. It can have one of the following values: SOL_SOCKET Set the options at the socket level. p Any protocol number. Set the options for protocol level p. For IPv4, see the IN.H header file for the IPPROTO values. For IPv6, see the IN6.H header file for the IPPROTO_IPV6 values. optname Interpreted by the protocol specified in level. Options at each protocol level are documented with the protocol. Refer to: o Socket Options for a list of socket options o TCP Protocol Options for a list of TCP options o IP Protocol Options for a list of IP options optval Points to a buffer containing the arguments of the specified option. All socket-level options other than SO_LINGER should be nonzero if the option is to be enabled, or zero if it is to be disabled. SO_LINGER uses a linger structure argument defined in the SOCKET.H header file. This structure specifies the desired state of the option and the linger interval. The option value for the SO_LINGER command is the address of a linger structure. If the socket is type SOCK_STREAM, which promises the reliable delivery of data, and l_onoff is nonzero, the system blocks the process on the close() attempt until it is able to transmit the data or until it decides it is unable to deliver the information. A timeout period, called the linger interval, is specified in l_ linger. If l_onoff is set to zero and a close() is issued, the system processes the close in a manner that allows the process to continue as soon as possible. optlen An integer specifying the size of the buffer pointed to by optval. 5 Description This function manipulates options associated with a socket. Options can exist at multiple protocol levels. They are always present at the uppermost socket level. When manipulating socket options, specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify the value of level as SOL_SOCKET. To manipulate options at any other level, supply the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by TCP, set the value for the level argument to the protocol number (IPPROTO_TCP) of TCP. For IPv4, see the IN.H header file for the various IPPROTO values. For IPv6, see the IN6.H header file for the various IPPROTO_IPV6 values. 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EACCES The calling process does not have appropriate permissions. EBADF The descriptor is invalid. EDOM The send and receive timeout values are too large to fit in the timeout fields of the socket structure. EINVAL The optlen argument is invalid. EISCONN The socket is already connected; the specified option cannot be set when the socket is in the connected state. EFAULT The optval argument is not in a readable part of the user address space. ENOBUFS The system had insufficient resources to complete the call. ENOPROTOOPT The option is unknown. ENOTSOCK The socket descriptor is invalid. EFAULT The optname argument is invalid. 4 shutdown() Shuts down all or part of a bidirectional connection on a socket. This function does not allow further receives or sends, or both. The $QIO equivalent is the IO$_DEACCESS function with the IO$M_SHUTDOWN function modifier. Format #include int shutdown ( int s, int how) ; 5 Arguments s A socket descriptor that is in a connected state as a result of a previous call to either connect() or accept(). how How the socket is to be shut down. Use one of the following values: 0 Do not allow further calls to recv() on the socket. 1 Do not allow further calls to send() on the socket. 2 Do not allow further calls to both send() and recv(). 5 Description This function allows communications on a socket to be shut down one direction at a time rather than all at once. You can use the shutdown() function to shut down one direction in a full-duplex (bidirectional) connection. Related Functions See also connect() and socket(). 5 Return_Values 0 Successful completion. -1 Error; errno is set to indicate the error. 5 Errors EBADF The socket descriptor is invalid. EINVAL The how argument is invalid. ENOBUFS The system has insufficient resources to complete the call. ENOTCONN The specified socket is not connected. ENOTSOCK The socket descriptor is invalid. 4 socket() Creates an endpoint for communication by returning a special kind of file descriptor called a socket descriptor, which is associated with a TCP/IP Services socket device channel. The $QIO equivalent is the IO$_SETMODE function. Format #include #include int socket ( int af, int type, int protocol ); 5 Arguments af The address family used in later references to the socket. Addresses specified in subsequent operations using the socket are interpreted according to this family. Use one of the following: o AF_INET for the IPv4 address family o AF_INET6 for the IPv6 address family o TCPIP$C_AUXS For a network application server with the LISTEN flag enabled, you specify the TCPIP$C_AUXS address family to obtain the connected device socket created by the auxiliary server in response to incoming network traffic. type The socket types are: o SOCK_STREAM - Provides sequenced, reliable, two-way, connection-based byte streams with an available out-of-band data transmission mechanism. o SOCK_DGRAM - Provides datagram transmissions. A datagram is a connectionless, unreliable data transmission mechanism. o SOCK_RAW - Provides access to internal network interfaces. Available only to users with the SYSPRV privilege. protocol The protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type using a given address format. However, if many protocols exist, a particular protocol must be specified with this argument. Use the protocol number that is specific to the address family. 5 Description This function provides the primary mechanism for creating sockets. The type and protocol of the socket affect the way the socket behaves and how it can be used. The operation of sockets is controlled by socket-level options, which are defined in the SOCKET.H header file and described in the setsockopt() function section of this chapter. Use the setsockopt() and getsockopt() functions to set and get options. Options take an integer argument that should be nonzero if the option is to be enabled or zero if it is to be disabled. SO_LINGER uses a linger structure argument (see linger Structure). Related Functions See also accept(), bind(), connect(), getsockname(), getsockopt(), socketpair(), listen(), read(), recv(), recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(), shutdown(), and write(). 5 Return_Values x A file descriptor that refers to the socket descriptor. -1 Error; errno is set to indicate the error. 5 Errors EACCES The process does not have sufficient privileges. EAFNOSUPPORT The specified address family is not supported in this version of the system. EMFILE The per-process descriptor table is full. ENETDOWN TCP/IP Services was not started. ENFILE No more file descriptors are available for the system. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system was unable to allocate kernel memory to increase the process descriptor table. EPERM The process is attempting to open a raw socket and does not have SYSTEM privilege. EPROTONOSUPPORT The socket in the specified address family is not supported. EPROTOTYPE The socket type is not supported by the protocol. ESOCKTNOSUPPORT The specified socket type is not supported in this address family. 4 socketpair() Creates a pair of connected sockets. Format #include int socketpair (int domain, int type, int protocol, int socket_vector[2]); 5 Arguments af The address family in which the sockets are to be created. Use one of the following: o AF_INET for the IPv4 address family o AF_INET6 for the IPv6 address family o TCPIP$C_AUXS or a network application server with the LISTEN flag enabled. Specify the TCPIP$C_AUXS address family to obtain the connected device socket created by the auxiliary server in response to incoming network traffic. type Specifies the type of sockets to be created. The socket types are: o SOCK_STREAM - Provides sequenced, reliable, two-way, connection-based byte streams with an available out-of-band data transmission mechanism. o SOCK_DGRAM - Supports datagrams (connectionless, unreliable data transmission mechanism). o SOCK_SEQPACKET - Provides sequenced, reliable, bidirectional, connection-mode transmission paths for records. A record can be sent using one or more output operations and received using one or more input operations, but a single operation never transfers part of more than one record. Use the MSG_EOR flag to determine the record boundaries. protocol The protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type using a given address format. However, if many protocols exist, a particular protocol must be specified with this argument. Use the protocol number that is specific to the address family. If the protocol argument is 0, the function uses the default protocol for the specified socket type. If the protocol argument is non-zero, the function uses the default protocol for the address family. socket_vector A 2-integer array to hold the file descriptors of the created socket pair. 5 Description This function creates an unbound pair of connected sockets in a specified address family, of a specified type, under the protocol optionally specified by the protocol argument. The two sockets will be identical. The file descriptors used in referencing the created sockets are returned in socket_vector[0] and socket_ vector[1]. Appropriate privileges are required to use the socketpair() function or to create some sockets. Related Functions See also socket(). 5 Return_Values 0 Successful completion -1 Error; errno is set to indicate the error. 5 Errors EACCES The process does not have sufficient privileges. EAFNOSUPPORT The specified address family is not supported in this version of the system. EMFILE The per-process descriptor table is full. ENETDOWN TCP/IP Services was not started. ENFILE No more file descriptors are available for the system. ENOBUFS The system has insufficient resources to complete the call. ENOMEM The system was unable to allocate kernel memory to increase the process descriptor table. EPERM The process is attempting to open a raw socket and does not have SYSTEM privilege. EPROTONOSUPPORT The socket in the specified address family is not supported. EPROTOTYPE The socket type is not supported by the protocol. ESOCKTNOSUPPORT The specified socket type is not supported in this address family. 4 write() Writes bytes from a buffer to a file or socket. The $QIO equivalent is the IO$_WRITEVBLK function. Format #include int write ( int d, void *buffer, int nbytes ); 5 Arguments d A descriptor that refers to a socket or file. buffer The address of a buffer from which the output data is to be taken. nbytes The maximum number of bytes involved in the write operation. 5 Description This function attempts to write a buffer of data to a socket or file. Related Functions See also socket(). 5 Return_Values x The number of bytes written to the socket or file. -1 Error; errno is set to indicate the error. 5 Errors EPIPE The socket is shut down for writing or is connection oriented, and the peer is closed or shut down for reading. In the latter case, if the socket is of type SOCK_STREAM, the SIGPIPE signal is generated to the calling process. EWOULDBLOCK The NBIO (nonblocking) flag is set for the socket descriptor, and the process is delayed during the write operation. EINVAL The nbytes argument is a negative value. EAGAIN The O_NONBLOCK flag is set on this file, and the process is delayed in the write operation. EBADF The d argument does not specify a valid file descriptor that is open for writing. EINTR A write() function on a pipe is interrupted by a signal, and no bytes have been transferred through the pipe. EINVAL On of the following errors occurred: o The STREAM or multiplexer referenced by d is linked (directly or indirectly) downstream from a multiplexer. o The file position pointer associated with the d argument was a negative value. EPERM An attempt was made to write to a socket of type SOCK_STREAM that is not connected to a peer socket. EPIPE An attempt was made to write to a pipe that has only one end open. An attempt was made to write to a pipe or FIFO that is not opened for reading by any process. A SIGPIPE signal is sent to the process. ERANGE An attempt was made to write to a STREAM socket where the value of nbytes is outside the specified minimum and maximum range, and the minimum value is nonzero. 3 System_Services System services routines let you write network applications. The $QIO system service uses network pseudodevice and TELNET port driver I/O function codes. 4 $ASSIGN Provides a calling process with an I/O channel, thereby allowing the calling process to perform I/O operations on the network pseudodevice. On Alpha and I64 systems, this service accepts 64-bit addresses. Format SYS$ASSIGN devnam, chan, [acmode], [mbxnam], [flags] C Prototype int sys$assign (void *devnam, unsigned short int *chan, unsigned int acmode, void *mbxnam,...); Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments devnam OpenVMS usage:device_name type: character-coded text string access: read only mechanism: (Alpha and I64) by 32- or 64-bit descriptor-fixed-length string descriptor (VAX) by 32-bit descriptor-fixed-length string descriptor Name of the device to which $ASSIGN is to assign a channel. The devnam argument is the address of a character string descriptor pointing to the network pseudodevice name string (either TCPIP$DEVICE: or SYS$NET:). chan OpenVMS usage:channel type: word (unsigned) access: write only mechanism: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference Number of the channel that is assigned. The chan argument is the address of a word into which $ASSIGN writes the channel number. acmode OpenVMS usage:access_mode type: longword (unsigned) access: read only mechanism: by value Access mode to be associated with the channel. I/O operations on the channel can be performed only from equal or more privileged access modes. The $PSLDEF macro defines the following symbols for the four access modes: Access Symbol Mode Numeric Value PSL$C_KERNEL Kernel 0 PSL$C_EXEC Executive 1 PSL$C_SUPER Supervisor 2 PSL$C_USER User 3 mbxnam OpenVMS usage:device_name type: character-coded text string access: read only mechanism: (Alpha and I64) by 32-bit or 64-bit descriptor-fixed-length string descriptor (VAX) by 32-bit descriptor-fixed-length string descriptor This argument is not used. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value An optional device-specific argument. The flags argument is a longword bit mask. For more information about the applicability of the flags argument for a particular device, refer to the OpenVMS I/O User's Reference Manual. 5 Description The $ASSIGN system service establishes a path to a device but does not check whether the calling process has the capability to do I/O operations to the device. The device drivers may apply privilege and protection restrictions. The calling process must have NETMBX privilege to assign a channel. System dynamic memory is required for the target device, and the I/O byte limit quota from the process buffer is used. When a channel is assigned to the TCPIP$DEVICE: network pseudodevice, the network software creates a new device called BGn, where n is a unique unit number. The corresponding channel number is used in any subsequent operation requests for that device. When the auxiliary server creates a process for a service with the LISTEN flag set, the server creates a device socket. In order for your application to receive the device socket, assign a channel to SYS$NET, which is the logical name of a network pseudodevice, and perform an appropriate $QIO(IO$_SETMODE) operation. Channels remain assigned either until they are explicitly deassigned with the Deassign I/O Channel ($DASSGN) service or, if they are user-mode channels, until the image that assigned the channel exits. 5 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_ACCVIO The caller cannot read the device string or string descriptor, or the caller cannot write the channel number. SS$_DEVALLOC The device is allocated to another process. SS$_DEVLSTFULL The system maximum number of BG: device units has been reached. SS$_EXQUOTA The process has exceeded its buffered I/O byte limit (BIOLM) quota. SS$_IVDEVNAM No device name was specified, the logical name translation failed, or the device name string contains invalid characters. SS$_IVLOGNAM The device name string has a length of zero or has more than 63 characters. SS$_NOIOCHAN No I/O channel is available for assignment. SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode. SS$_NOSUCHDEV The specified device does not exist. 4 $CANCEL Cancels all pending I/O requests on a specified channel. Related Functions The equivalent Sockets API function is close(). Format SYS$CANCEL chan C Prototype int sys$cancel (unsigned short int chan); Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value I/O channel on which I/O is to be canceled. The chan argument is a word containing the channel number. 5 Description To cancel I/O on a channel, the access mode of the calling process must be equal to or more privileged than the access mode of the process that made the original channel assignment. The $CANCEL service requires system dynamic memory and uses the process's buffered I/O limit (BIOLM) quota. When a request currently in progress is canceled, the driver is notified immediately. Actual cancellation may or may not occur immediately, depending on the logical state of the driver. When cancellation does occur, the action taken for I/O in progress is similar to that taken for queued requests. For example: o The specified event flag is set. o The first word of the I/O status block, if specified, is set to SS$_CANCEL if the I/O request is queued, or to SS$_ABORT if the I/O operation is in progress. o If the asynchronous system trap (AST) is specified, it is queued. For proper synchronization between this service and the actual canceling of I/O requests to take place, the issuing process must wait for the I/O process to complete normally. Note that the I/O has been canceled. Outstanding I/O requests are canceled automatically at image exit. 5 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_ABORT A physical line went down during a network connect operation. SS$_CANCEL The I/O operation was canceled by executing a $CANCEL system service. SS$_EXQUOTA The process has exceeded its buffered I/O limit (BIOLM) quota. SS$_INSFMEM Insufficient system dynamic memory to cancel the I/O. SS$_IVCHAN An invalid channel was specified (that is, a channel number of 0 or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode. 4 $DASSGN Deassigns (releases) an I/O channel previously acquired using the Assign I/O Channel ($ASSIGN) service. Related Functions The equivalent Sockets API function is close(). Format SYS$DASSGN chan C Prototype int sys$dassgn (unsigned short int chan); Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value Number of the I/O channel to be deassigned. The chan argument is a word containing this number. 5 Description After all communication is completed, use the $DASSGN system service to free an I/O channel. A $DASSGN operation executed on a channel associated with a network pseudodevice does the following: o Ends all pending operations to send or receive data at $QIO level ($CANCEL system service). o Clears the port associated with the channel. When executing the $DASSGN system service for TCP sockets, the socket remains until the connection is closed on both the local and remote sides. o Ends all communications with the network pseudodevice that the I/O channel identifies. o Frees the channel associated with the network pseudodevice. An I/O channel can be deassigned only from an access mode equal to or more privileged than the access mode from which the original channel assignment was made. I/O channels assigned from user mode are automatically deassigned at image exit. NOTE Even after a $DASSGN has been issued, a TCP socket may remain until the TCP close timeout interval expires. The default and maximum timeout interval is either 10 minutes if the peer host is not responding or 30 seconds after acknowledging the socket close. Although the TCP socket is open, you cannot make a reference to that socket after issuing a $DASSGN. 5 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_IVCHAN An invalid channel number was specified (that is, a channel number of zero or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned or is assigned from a more privileged access mode. 4 $QIO Queues an I/O request to a channel associated with a network pseudodevice. The $QIO service is completed asynchronously; that is, it returns to the caller immediately after queuing the I/O request, without waiting for the I/O operation to be completed. For synchronous completion, use the Queue I/O Request and Wait ($QIOW) service. The $QIOW service is identical to the $QIO service, except the $QIOW returns to the caller after the I/O operation has completed. On Alpha and I64 systems, this service accepts 64-bit addresses. Format SYS$QIO [efn],chan,func, [iosb],[astadr],[astprm], [p1],[p2],[p3],[p4], [p5],[p6] C Prototype int sys$qio (unsigned int efn, unsigned short int chan, unsigned int func, struct _iosb *iosb, void (*astadr)(__unknown_params), __int64 astprm, void *p1, __int64 p2, __int64 p3, __int64 p4, __int64 p5, __int64 p6); Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned. 5 Arguments efn OpenVMS usage:ef_number type: longword (unsigned) access: read only mechanism: by value Event flag that $QIO sets when the I/O operation completes. The efn argument is a longword value containing the number of the event flag; however, $QIO uses only the low-order byte. If efn is not specified, event flag 0 is set. The specified event flag is set if the service terminates without queuing an I/O request. chan OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value I/O channel that is assigned to the device to which the request is directed. The chan argument is a word value containing the number of the I/O channel. func OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by value Function codes and function modifiers specifying the operation to be performed. The func argument is a longword containing the function code. For information about the network pseudodevice and TELNET device function codes and modifiers, see Network Pseudodevice Driver Functions and TELNET Port Driver I/O Function Codes. iosb OpenVMS usage:io_status_block type: quadword (unsigned) access: write only mechanism: (Alpha and I64) by 32-bit reference or 64-bit reference (VAX) by 32-bit reference I/O status block to receive the final completion status of the I/O operation. The iosb is the address of the quadword I/O status block. When the $QIO begins executing, it clears the event flag. The $QIO also clears the quadword I/O status block if the iosb argument is specified. Although the iosb argument is optional, HP strongly recommends that you specify it, for the following reasons: o If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion. o If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH. o The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $QIO service. The condition value returned in R0 provides information about the success or failure of the service call itself; the condition values returned in the I/O status block give information on the success or failure of the service operation. Therefore, to determine the success or failure of the $QIO call, check the condition values returned in both the R0 and the I/O status block. astadr OpenVMS usage:ast_procedure type: procedure value access: call without stack unwinding mechanism: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference AST service routine to be executed when the I/O completes. The astadr argument is the address of the AST routine. The AST routine executes at the access mode of the caller of $QIO. astprm OpenVMS usage:user_arg type: quadword unsigned (Alpha and I64); longword unsigned (VAX) access: read only mechanism: (Alpha and I64) by 32- or 64-bit value (VAX) by 32-bit value AST parameter to be passed to the AST service routine. On Alpha and I64 systems, the astprm argument is a quadword value containing the AST parameter. On VAX systems, the astprm argument is a longword value containing the AST parameter. p1 to p6 OpenVMS usage:varying_arg type: quadword unsigned (Alpha and I64); longword unsigned (VAX) access: read only mechanism: (Alpha and I64) by 32- or 64-bit reference or by 64-bit value depending on the I/O function (VAX) by 32-bit reference or by 32-bit value depending on the I/O function Optional device- and function-specific I/O request arguments. The parameter values contained in these arguments vary according to the function for which they are used. See Network Pseudodevice Driver Functions for descriptions of the network pseudodevice driver I/O function codes. 5 Description The Queue I/O Request service operates only on assigned I/O channels and only from access modes that are equal to or more privileged than the access mode from which the original channel assignment was made. For TCP/IP Services, $QIO uses the following system resources: o The process's AST limit (ASTLM) quota, if an AST service routine is specified. o System dynamic memory, which is required to queue the I/O request. System dynamic memory requirements are protocol specific. o Additional memory, on a device-dependent basis. For $QIO, completion can be synchronized as follows: o By specifying the astadr argument to have an AST routine execute when the I/O is completed. o By calling the $SYNCH synchronize service to await completion of the I/O operation. (If you want your I/O operation to complete synchronously, use the $QIOW system service instead.) 5 Condition_Values_Returned Each function used with $QIO has its own error codes. See the error codes listed under the individual descriptions of the I/O function code in the remainder of this chapter. 5 Network_Pseudodevice_Driver_Functions The network pseudodevice allows physical, logical, and virtual I/O functions. The physical and logical I/O functions are used only with the IP layer. See the following table for a list of the basic I/O functions and their modifiers. The sections that follow describe in greater detail the operation of these I/O functions. The following table describes the network pseudodevice driver I/O functions. Function Code and Function Arguments Modifier Description IO$_ACCESS p3,p4 IO$M_ACCEPT Opens a connection. IO$M_EXTEND IO$M_NOW IO$_ACPCONTROL p1, Performs an ACP (ancillary p2, p3, p4 control process) operation. IO$_DEACCESS p4 IO$M_NOW Aborts or closes a IO$M_SHUTDOWN connection. IO$_READVBLK IO$M_EXTEND Reads a virtual block. p1,p2,p3,p4,p6 IO$M_ INTERRUPT IO$M_LOCKBUF Controls the buffer IO$M_PURGE operations. IO$_SENSEMODE Reads the network p2,p3,p4,p6 pseudodevice characteristics. IO$_SENSECHAR Reads the network p2,p3,p4,p6 pseudodevice characteristics. IO$_SETMODE p1,p2, IO$M_OUTBAND Sets the network p3,p4,p5 IO$M_READATTN pseudodevice characteristics IO$M_WRTATTN for subsequent operations. IO$_SETCHAR p1,p2, IO$M_OUTBAND Sets the network p3,p4,p5 IO$M_READATTN pseudodevice characteristics IO$M_WRTEATTN for subsequent operations. IO$_WRITEVBLK IO$M_ Writes a virtual block. p1,p2,p3,p4,p5 INTERRUPT 6 IO$_ACCESS When using a connection-oriented protocol, such as TCP, the IO$_ ACCESS function initiates a connection and specifies a remote port number and IP address. When using a connectionless protocol, such as UDP, the IO$_ACCESS function sets the remote port number and IP address. For TCP, a connection request times out at a specified interval (75 seconds is the default). This interval can be changed by setting the inet subsystem parameter tcp_keepinit. The program can also set a specific timeout interval for a socket that it has created, as described in TCP Protocol Options. If a connection fails, you must deallocate the socket and then create a new socket before trying to reconnect. Related Functions The equivalent Sockets API function is connect(). 7 Arguments p3 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor The remote port number and IP address of the host to connect. The p3 argument is the address of an item_list_2 descriptor that points to the socket address structure containing the remote port number and IP address. 7 Function_Modifiers IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_BADPARAM Programming error that occurred for one of the following reasons: o $QIO system service was specified without a socket. o An IO$_ACCESS function was specified without the address of a remote socket name (p3 was null). SS$_BUGCHECK Inconsistent state. Report the problem to your HP support representative. SS$_CANCEL The I/O operation was canceled by a $CANCEL system service. SS$_CONNECFAIL The connection to a network object timed out or failed. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_DUPLNAM A network configuration error. No ports were available for new connections. SS$_EXQUOTA The process has exceeded a process quota. SS$_FILALRACC The specified socket name is already in use by one of the following: o On a raw socket, the remote IP address was already specified on a previous IO$_ACCESS call. o On a datagram, the remote IP address was already specified on a previous IO$_ACCESS call. o On a stream socket, the IO$_ACCESS function targeted a stream socket that was already connected. SS$_ILLCNTRFUNC Illegal function. SS$_INSFMEM Insufficient system dynamic memory to complete the service. SS$_IVADDR The specified IP address was not found, or an invalid port number and IP address combination was specified with the IO$_ACCESS function. Port 0 is not allowed with the IO$_ACCESS function. SS$_IVBUFLEN The size of the socket name structure specified with the IO$_ACCESS function was invalid. SS$_LINKABORT The remote socket closed the connection. SS$_NOLICENSE The TCP/IP Services license is not present. SS$_PROTOCOL A network protocol error occurred. The address family specified in the socket address structure is not supported. SS$_REJECT The network connection is rejected for one of the following reasons: o An attempt was made to connect to a remote socket that is already connected. o An error was encountered while establishing the connection o The peer socket refused the connection request or is closing the connection. SS$_SHUT The local or remote node is no longer accepting connections. SS$_SUSPENDED The system detected a condition that might cause the operation to block. SS$_TIMEOUT A TCP connection timed out before the connection could be established. SS$_UNREACHABLE The remote node is currently unreachable. 6 IO$_ACCESS|IO$M_ACCEPT This function is used with a connection-based protocol, such as TCP, to accept a new connection on a passive socket. This function completes the first connection on the queue of pending connections. Related Functions The equivalent Sockets API function is accept() . 7 Arguments p3 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_3 descriptor The remote port number and IP address of a new connection. The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the remote port number and IP address of the new connection is written. p4 OpenVMS usage:channel type: word (unsigned) access: write only mechanism: by reference The I/O channel number assigned to a new connection. The p4 argument is the address of a word into which the new connection's channel number is written. 7 Function_Modifiers IO$M_EXTEND Allows the usage of BSD Version 4.4 formatted socket address structures. Use this modifier to operate in the IPv6 environment. IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_BADPARAM Programming error that occurred for one of the following reasons: o $QIO system service was specified without a socket. o A IO$_ACCESS|IO$M_ACCEPT function was specified without the address of the channel for the new connection (p4 was null or invalid). SS$_BUGCHECK Inconsistent state. Report the problem to your HP support representative. SS$_CANCEL The I/O operation was canceled by a $CANCEL system service. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_EXQUOTA The process has exceeded a process quota. SS$_FILALRACC The specified socket name is already in use by one of the following: o On a raw socket, the remote IP address was already specified on a previous IO$_ACCESS call. o On a datagram, the remote IP address was already specified on a previous IO$_ACCESS call. o On a stream socket, the IO$_ACCESS function targeted a stream socket that was already connected. SS$_ILLCNTRFUNC Illegal function. SS$_INSFMEM Insufficient system dynamic memory to complete the service. SS$_IVADDR The specified IP address was not found, or an invalid port number and IP address combination was specified with the IO$_ACCESS function. Port 0 is not allowed with the IO$_ACCESS function. SS$_IVBUFLEN The size of the socket name structure specified with the IO$_ACCESS function was invalid. SS$_LINKABORT The remote socket closed the connection. SS$_NOLICENSE The TCP/IP Services license is not present. SS$_PROTOCOL A network protocol error occurred. The address family specified in the socket address structure is not supported. SS$_REJECT The network connection is rejected for one of the following reasons: o An attempt was made to connect to a remote socket that is already connected. o An error was encountered while establishing the connection o The peer socket refused the connection request or is closing the connection. SS$_SHUT The local or remote node is no longer accepting connections. SS$_SUSPENDED The system detected a condition that might cause the operation to block. SS$_TIMEOUT A TCP connection timed out before the connection could be established. SS$_UNREACHABLE The remote node is currently unreachable. 6 IO$_ACPCONTROL The IO$_ACPCONTROL function accesses the network ACP to retrieve information from the host and the network database files. Related Functions The equivalent Sockets API functions are gethostbyaddr(), gethostbyname(), getnetbyaddr(), and getnetbyname(). 7 Arguments p1 OpenVMS usage:subfunction_code type: longword (unsigned) access: read only mechanism: by descriptor-fixed-length descriptor A longword identifying the network ACP operation to perform. The p1 argument is the address of a descriptor pointing to this longword. To specify the network ACP operation to perform, select a subfunction code from the first table below and a call code from the second table. The following table defines subfunction codes for network ACP operations. . Subfunction Code Description INETACP_FUNC$C_ Get the host name of the specified IP GETHOSTBYADDR address from the hosts database. INETACP_FUNC$C_ Get the IP address of the specified GETHOSTBYNAME host from the hosts database. INETACP_FUNC$C_ Get the network name of the specified GETNETBYADDR IP address from the network database. INETACP_FUNC$C_ Get the IP address of the specified GETNETBYNAME network from the network database. The following table defines call codes for network ACP operations. Call Code Description INETACP$C_ALIASES Returns the list of alias names associated with the specified host or network from the internet hosts or network database. INETACP$C_TRANS Returns the IP address associated with the specified host or network as a 32-bit value in network byte order. INETACPC$C_HOSTENT_ Returns full host information in a OFFSET modified hostent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure. INETACP$C_NETENT_ Returns full network information in OFFSET a modified netent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure. IO$_ACPCONTROL searches the local hosts database for the host's name. If a matching host name is not found in the local hosts database, IO$_ACPCONTROL then searches the BIND database if the BIND resolver is enabled. p2 OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor-fixed-length string descriptor Input string for the network ACP operation containing one of the following: host IP address, host name, network IP address, or network name. The p2 argument is the address of a string descriptor pointing to the input string. The input string must be in an area of memory that is capable of being read and written to. All IP addresses are specified in dotted-decimal notation. p3 OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length in bytes of the output buffer returned by IO$_ACPCONTROL. The p3 argument is the address of a word in which the length of the output buffer is written. p4 OpenVMS usage:buffer type: vector byte (unsigned) access: write only mechanism: by descriptor-fixed-length descriptor Buffer into which IO$_ACPCONTROL writes its output data. The p4 argument is the address of a descriptor pointing to the output buffer. The format of the data returned in the output buffer is dictated by the call code specified by the p1 argument. o Strings returned by IO$_ACPCONTROL with a call code of INETACP$C_ALIASES consist of one of the following: host IP address, host name, network IP address, or network name. All IP addresses are formatted using dotted-decimal notation. Alias names are separated by a null character (0). The length of the returned string includes all null characters that separate alias names. o IP addresses returned by IO$_ACPCONTROL with a call code of INETACP$C_TRANS are 32-bit values in network byte order. o All hostent and netent structures returned by IO$_ ACPCONTROL with a call code of INETACP$C_HOSTENT_OFFSET or INETACP$C_NETENT_OFFSET are modified; pointers are replaced with offsets from the beginning of the structure. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully SS$_ABORT An error was detected while performing an ACP function. SS$_BADPARAM Programming or internal error. A bad parameter (name or address) was specified in the call. SS$_BUFFEROVF Programming error. There was not enough space for returning all alias names in the call. SS$_ENDOFFILE The information requested is not in the database. SS$_ILLCNTRFUNC Illegal function. SS$_NOPRIV The privilege level was insufficient for the execution of an ACP function. SS$_RESULTOVF The ACP overflowed the buffer in returning a parameter. SS$_SHUT The local or remote node is no longer accepting connections. 6 IO$_DEACCESS The IO$_DEACCESS function closes a connection and deletes a socket. Any pending messages queued for transmission are sent before tearing down the connection. When used with the IO$M_SHUTDOWN function modifier, the IO$_ DEACCESS function shuts down all or part of a bidirectional connection on a socket. Use the p4 argument to specify the disposition of pending I/O operations on the socket. You can specify a wait time or time-to-linger socket parameter (TCPIP$C_LINGER option) for transmission completion before disconnecting the connection. Use the IO$_SETMODE function to set and clear the TCPIP$C_LINGER option. If you set the TCPIP$C_LINGER option, a $QIO call that uses the IO$_DEACCESS function allows data queued to the socket to arrive at the destination. The system is blocked until data arrives at the remote socket. The socket data structure remains open for the duration of the TCP idle time interval. If you do not set the TCPIP$C_LINGER option (option is set to 0), a $QIO call that uses the IO$_DEACCESS function discards any data queued to the socket and deallocates the socket data structure. NOTE For compatibility with UNIX, TCP/IP Services forces a time to linger of 2 minutes on TCP stream sockets. Related Functions The equivalent Sockets API functions are close() and shutdown(). 7 Arguments p4 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Longword of shutdown flags to specify the disposition of pending I/O operations on the socket. The p4 argument is used only with the IO$M_SHUTDOWN function modifier. The following table lists available shutdown flags. Shutdown Flag Description TCPIP$C_DSC_ Discards messages from the receive queue and RCV disallows further receiving. Pending messages in the receive queue for this connection are discarded. TCPIP$C_DSC_ Discards messages from the send queue and SND disallows sending new messages. Pending messages in the transmit queue for this connection are discarded. TCPIP$C_DSC_ Discards all messages and disallows both ALL sending and receiving. All pending messages are discarded. Specifying this flag has the same effect as issuing a $CANCEL QIO followed by an IO$_DEACCESS QIO without specifying any flags. 7 Function_Modifiers IO$M_SHUTDOWN Causes all or part of a full-duplex connection on a socket to be shut down. IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_BADPARAM The IO$_DEACCESS operation failed to specify a socket. SS$_CANCEL The I/O operation was canceled by a $CANCEL system service. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_NOLINKS The specified socket was not connected. SS$_SHUT The local or remote node is no longer accepting connections. SS$_SUSPENDED The system detected a condition that might cause the operation to block. 6 IO$_READVBLK The IO$_READVBLK function transfers data received from an internet host to the specified user buffers. Use both p1 and p2 arguments to specify a single user buffer. Use the p6 argument to specify multiple buffers. For connection-oriented protocols, such as TCP, data is buffered in system space as a stream of bytes. The IO$_READVBLK function completes when one of the following occurs: o There is no more data buffered in system space for this socket. o There is no more available space in the user buffer. Data that is buffered in system space but did not fit in the user buffer is available to the user in subsequent $QIOs. For connectionless protocols, datagram and raw socket data is buffered in system space as a chain of records. The user buffer specified with a IO$_READVBLK function is filled with data that is buffered in one record. Each IO$_READVBLK reads data from one record. The IO$_READVBLK function completes when one of the following occurs: o All data from a record is transferred to the user buffer. o There is no more available space in the user buffer. Any data remaining in the current record that did not fit in the user buffer is discarded. A subsequent $QIO reads data from the next record buffered in system space. Use the TCP/IP management command SHOW DEVICE_SOCKET/FULL to display counters related to read operations. Related Functions The equivalent Sockets API functions are read(), recv(), recvfrom(), and recvmsg(). 7 Arguments p1 OpenVMS usage:buffer type: vector byte (unsigned) access: read only mechanism: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference The address of the buffer to receive the incoming data. The length of this buffer is specified by the p2 argument. p2 OpenVMS usage:buffer_length type: access: quadword unsigned (Alpha and I64); longword unsigned (VAX) mechanism: read only (Alpha and I64) by 64-bit value The length (in bytes) of the buffer available to hold the incoming data. The address of this buffer is specified by the p1 argument. p3 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_3 descriptor The remote port number and IP address of the source of the datagram or raw IP message (not TCP). The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the remote port number and IP address of the message source is written. p4 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Longword of flags to specify attributes for the read operations. The following table lists the available read flags. Read Flag Description TCPIP$C_MSG_OOB Reads an out-of-band byte. TCPIP$C_MSG_PEEK Reads a message but leaves the message in the queue. TCPIP$C_MSG_NBIO Does not block the I/O operation if the receive queue is empty (similar to using IO$M_NOWAIT). TCPIP$C_MSG_PURGE Flushes data from the queue (similar to using IO$M_PURGE). TCPIP$C_MSG_ Blocks the completion of the operation until BLOCKALL the buffer is filled completely or until the connection is closed (similar to using IO$M_ LOCKBUF). p6 OpenVMS usage:buffer_list type: vector byte (unsigned) access: read only mechanism: (Alpha and I64) by 32- or 64-bit descriptor-fixed-length descriptor (VAX) by 32-bit descriptor-fixed-length descriptor Output buffer list describing one or more buffers to hold the incoming data. The p6 argument is the 32- or 64-bit address (on Alpha and I64 systems) or the 32-bit address (on VAX systems) of a descriptor that points to a output buffer list. Buffers are filled in the order specified by the output buffer list. The transfer-length value returned in the I/O status block is the total number of bytes transferred to all buffers. If you use the p1 and p2 arguments, do not use the p6 argument; they are mutually exclusive. 7 Function_Modifiers IO$M_EXTEND Specifies the format of the socket address structure to return when used with the p3 argument. When specified, a BSD Version 4.4 formatted socket address structure is returned that identifies the source of the received UDP datagram or raw IP message. To operate in an IPv6 environment, you must set the IO$M_EXTEND modifier. IO$M_INTERRUPT Reads an out-of-band (OOB) message. This has the same effect as specifying the TCPIP$C_MSG_OOB flag in the p4 argument. On receiving an OOB character, TCP/IP stores the pointer in the received stream with the character that precedes the OOB character. A read operation with a user-buffer size larger than the size of the received stream up to the OOB character completes and returns to the user the received stream up to, but not including, the OOB character. To determine whether the socket must issue more read $QIOs before getting all the characters from the stream preceding an OOB character, poll the socket. To do this, issue a $QIO with the $IO_SENSEMODE function, and the TCPIP$C_IOCTL subfunction that specifies the SIOCATMARK command. The SIOCATMARK values are as follows: o 0 = Issue more read $QIOs to read more data before reading the OOB. o 1 = The next read $QIO will return the OOB character. Polling a socket is particularly useful when the OOBINLINE socket option is set. When the OOBINLINE is set, TCP/IP reads the OOB character with the characters in the stream (IO$_READVBLK), but not before reading the preceding characters. Use this polling mechanism to determine whether the first character in the user buffer on the next read is an OOB character. On a socket without the OOBINLINE option set, a received OOB character will always be read by issuing a $QIO with either the IO$_READVBLK|IO$M_INTERRUPT or IO$_READVBLK and the TCPIP$C_MSG_OOB flag set. This can occur regardless of how many preceding characters in the stream have been returned to the user. IO$M_LOCKBUF Blocks the completion of the I/O operation until the user buffer is completely filled or until the connection is closed. This is particularly useful when you want to minimize the number of $QIO service calls issued to read a data stream of a set size. This function modifier supports only stream protocols. IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code. IO$M_PURGE Flushes data from the socket receive queue (discards data). If the user buffer is larger than the amount of data in the queue, all data is flushed. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_ABORT Programming error, INET management error, or hardware error. The execution of the I/O was aborted. SS$_ACCVIO Access to an invalid memory location or buffer occurred. SS$_BADPARAM One of the following methods was used to specify a $QIO function with an invalid parameter: o An I/O function executed without specifying a device socket. First issue a $QIO with the IO$_SETMODE function and the proper parameters to create the device socket. o An IO$_READVBLK function that does not specify a correct buffer address (p1 or p6 is null). o An IO$_READVBLK function specified an invalid vectored buffer (p6 is an invalid descriptor). o The socket has the OOBINLINE option set, or there is no OOB character in the socket's OOB queue because the character was either already read or never received. This condition happens only if you use the IO$M_INTERRUPT modifier or set the TCPIP$C_MSG_OOB flag with IO$_READVBLK. SS$_CANCEL The I/O operation was canceled by a $CANCEL system service. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_INSFMEM INET management or programming error. There is not enough buffer space for allocation. The INET software needs more buffer space. You should set a higher quota for the dynamic buffer space, or shut down and restart TCP/IP Services with a larger static buffer space. SS$_IVBUFLEN Programming error occurred for one of the following reasons: o The size of the buffer for an I/O function is insufficient. o An IO$_READVBLK specified a correct buffer address (p1 valid), but does not specify a buffer length (p2 is null). SS$_LINKDISCON A virtual circuit (TCP/IP) was closed at the initiative of the peer. SS$_NOLINKS Programming error. Read attempt on unconnected TCP socket. SS$_SHUT The network is being shut down. SS$_SUSPENDED The operation is blocked for one of the following reasons: o No messages were received, so the receive operation cannot complete. The socket is marked as nonblocking. o The socket has the OOBINLINE option clear, and the OOB character has already been read. SS$_TIMEOUT This applies to a socket that has KEEPALIVE set. The connection was idle for longer than the timeout interval (10 minutes is the default). For more information, see TCP Protocol Options. SS$_UNREACHABLE Communication status. The remote host or network is unreachable. 6 IO$_SENSEMODE/IO$_SENSECHAR The IO$_SENSEMODE and IO$_SENSECHAR functions return one or more parameters (characteristics) pertaining to the network driver. Socket names (local and remote peer) are returned by using IO$_ SENSEMODE's p3 and p4 arguments. Other parameters such as socket and protocol options, are specified in an output parameter list using the IO$_SENSEMODE p6 argument. IO$_SENSEMODE p3 and p4 arguments can be used with the p6 argument in a single $QIO system service to return socket names as well as socket and protocol options. IO$_SENSEMODE processes arguments in this order: p3, p4, p6. If IO$_SENSEMODE detects an error, the I/O status block (IOSB) contains the error and argument address or the value that was at fault. Refer to individual argument descriptions for details about specifying the type and format of output parameters. 7 Arguments p3 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_3 descriptor The port number and IP address of the local name associated with the socket. The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the local name is written. The equivalent Sockets API function is getsockname(). p4 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_3 descriptor The port number and IP address of the remote name associated with the socket's peer. The p4 argument is the address of an item_ list_3 descriptor that points to the socket address structure into which the peer name is written. The equivalent Sockets API function is getpeername(). p6 OpenVMS usage:output_parameter_list type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor Output parameter list describing one or more parameters to return. The p6 argument is the address of an item_list_2 descriptor that points to and identifies the type of output parameter list. The equivalent Sockets API functions are getsockopt() and ioctl(). 7 Function_Modifiers IO$M_EXTEND Specifies the format of the socket address structure to return when used with the p3 or p4 arguments. When specified, a BSD Version 4.4 formatted socket address structure is returned. Specify the IO$M_EXTEND modifier to operate in an IPv6 environment. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_ACCVIO The service cannot access a buffer specified by one or more arguments. SS$_BADPARAM Programming error occurred for one of the following reasons: o $QIO system service was specified without a socket. o Error occurred processing a socket or protocol option. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_ILLCNTRFUNC Programming error. The operation is unsupported for one of the following reasons: o An invalid IO$_SENSEMODE function for the interface was specified. The interface does not have an IOCTL routine. o An IO$_SENSEMODE function that requires a socket was specified, but the device did not have one. Create a socket and then issue the function. o An unsupported operation was performed on at least one of the following protocols: raw IP, datagram, or stream sockets. SS$_INSFMEM Insufficient system dynamic memory to complete the service. SS$_IVBUFLEN The size of a socket option buffer specified with the IO$_SENSEMODE function was invalid. SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the Address Resolution Protocol (ARP) table. An attempt to show or delete an ARP table entry failed. SS$_NOLINKS The specified socket was not connected. SS$_NOOPER Programming error. An attempt to get ARP information occurred without OPER privilege. SS$_PROTOCOL A network protocol error occurred. The address family specified in the socket address structure is not supported. SS$_SHUT The local or remote node is no longer accepting connections. SS$_UNREACHABLE The remote node is currently unreachable. 6 IO$_SETMODE/IO$_SETCHAR The IO$_SETMODE and IO$_SETCHAR functions set one or more parameters (characteristics) pertaining to the network driver. Sockets are created using the IO$_SETMODE p1 argument. Names are assigned to sockets using the IO$_SETMODE p3 argument. Active sockets are converted to passive sockets using the IO$_SETMODE p4 argument. Other parameters, such as socket and protocol options, are specified in an input parameter list using the IO$_SETMODE p5 argument. The IO$_SETMODE p1, p3, and p4 arguments can be used with the p5 argument in a single $QIO system service to set socket names as well as socket and protocol options. IO$_SETMODE processes arguments in this order: p1, p3, p4, p5. If IO$_SETMODE detects an error, the I/O status block (IOSB) contains the error and argument address or the value that was at fault. Refer to individual argument descriptions for details about specifying the type and format of input parameters. 7 Arguments p1 OpenVMS usage:socket_characteristics type: longword (unsigned) access: read only mechanism: by reference Longword specifying the protocol, socket type, and address family of a new socket. The p1 argument is the address of the longword containing the socket characteristics. The newly created socket is marked privileged if the image that creates a socket runs in a process that has BYPASS, OPER, or SYSPRV privilege. The following table shows protocol codes: Protocol Description TCPIP$C_TCP TCP/IP protocol TCPIP$C_UDP UDP/IP protocol TCPIP$C_RAW_IP IP protocol The following table lists the valid socket types. Socket Type Description TCPIP$C_STREAM Permits bidirectional, reliable, sequenced, and unduplicated data flow without record boundaries. TCPIP$C_DGRAM Permits bidirectional data flow with record boundaries. No provisions for sequencing, reliability, or unduplicated messages. TCPIP$C_RAW Permits access to the IP layer; used to develop new protocols that are layered upon the IP layer. The following table shows address family codes: Address Family Description TCPIP$C_AF_INET IPv4 Internet domain (default). TCPIP$C_AF_ IPv6 Internet domain. INET6 TCPIP$C_AUXS Accept hand-off of a socket already created and initialized by the auxiliary server. The equivalent Sockets API function is socket(). p3 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor The local name (that is, port number and IP address) to assign to the socket. The p3 argument is the address of an item_list_2 descriptor that points to the socket address structure containing the local name. The equivalent Sockets API function is bind() . p4 OpenVMS usage:connection_backlog type: byte (unsigned) access: read only mechanism: by value Maximum limit of outstanding connection requests for a socket that is connection oriented. If more connection requests are received than are specified, the additional requests are ignored so that TCP retries can succeed. The equivalent Sockets API function is listen(). p5 OpenVMS usage:input_parameter_list type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor Input parameter list describing one or more parameters to set. The p5 argument is the address of an item_list_2 descriptor that points to and identifies the type of input parameter list. The equivalent Sockets API functions are setsockopt() and ioctl(). 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_ACCVIO The service cannot access a buffer specified by one or more arguments. SS$_BADPARAM Programming error that occurred for one of the following reasons: o $QIO system service was specified without a socket. o Error occurred processing a socket or protocol option. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_DUPLNAM Programming error. The port being bound is already in use. An attempt to bind the socket to an address and port failed. SS$_FILALRACC Programming error. The IP address is already in use. An attempt to bind the socket to an address and port failed. SS$_ILLCNTRFUNC Programming error. An attempt to perform an IO$_SETMODE function required a socket, but the device did not have one. Create a socket before issuing the function. SS$_IVADDR Programming error. The IP address you specified using the IO$_SETMODE function was not placed into the system. This resulted in an invalid port number or IP address combination. The IP address was invalid for one of the following reasons: o An attempt was made to exceed the limit of allowable permanent entries in the ARP table. o An attempt was made to bind a raw IP socket when there are no interfaces defined in the system. o An attempt was made to bind a raw IP socket to a null Internet address. SS$_INSFMEM Insufficient system dynamic memory to complete the service. SS$_IVBUFLEN The size of a socket option buffer specified with the IO$_SETMODE function was invalid. SS$_NOLICENSE Programming or system management error. A TCP/IP Services license is not present. SS$_NOOPER Programming or INET management error. An attempt to was made to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. There are not enough privileges for the attempted operation for one of the following reasons: o An attempt was made to broadcast an IP datagram on a process without SYSPRV, BYPASS, or OPER privilege. o An attempt was made to use a reserved port number lower than 1024. o An attempt was made to access a process that requires SYSPRV or BYPASS privilege. o An attempt was made to use raw IP on a privileged socket that requires the SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. An attempt was made to show or delete an ARP table entry failed because the IP address is not found. SS$_NOSUCHNODE Programming error or INET management error. An attempt was made to delete a route from the routing table failed because the entry was not found. SS$_PROTOCOL Programming error. A specified protocol or address family caused an error for one of the following reasons: o An invalid protocol type was specified at socket creation. o An unsupported protocol was specified. o The address family is unsupported for one of the following reasons: - An unsupported address family was specified. Instead, specify the address family (TCPIP$C_AF_INET, TCPIP$C_AF_INET6, or TCPIP$C_UNSPEC). - An unsupported address family for the local IP address was specified. Instead, specify the address family (TCPIP$C_AF_INET or TCPIP$C_AF_INET6). - An unsupported address family for the IP address of the routing module was specified. Instead, specify the address family (TCPIP$C_AF_INET or TCPIP$C_AF_INET6). SS$_SHUT The local or remote node is no longer accepting connections. 6 IO$_SETMODE|IO$M_OUTBAND The IO$_SETMODE|IO$M_OUTBAND function/modifier combination requests that the asynchronous system trap (AST) for an out- of-band (OOB) character be delivered to the requesting process. This is to be done only when an OOB character is received on the socket and there is no waiting read request. The socket must be a TCP (stream) socket. The Enable OOB character AST function allows an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before a new AST can be delivered. This function is subject to AST quotas. 7 Arguments p1 OpenVMS usage:ast_procedure type: procedure value access: call without stack unwinding mechanism: by reference To enable the AST, the p1 argument is the address of the OOB character AST routine. To disable the AST, p1 equals 0. p2 OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value AST parameter to be delivered to the AST routine specified by the p1 argument. p3 OpenVMS usage:access_mode type: longword (unsigned) access: read only mechanism: by value Access mode to deliver the AST. 7 Condition_Values_Returned SS$_NORMAL The service completed successfully. SS$_ABORT Programming, INET management, or hardware error. SS$_ACCVIO Programming error. An attempt to access an invalid memory location or buffer occurred. SS$_BADPARAM Programming error. A $QIO service with an invalid parameter occurred for one of the following reasons: o An attempt was made to execute an IO$_ SETMODE function (all functions except socket creation) without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_ SETMODE function and correct parameters. o A socket option was specified incorrectly. SS$_DEVACTIVE INET management error. An attempt to change the static parameters occurred. If new parameters are needed, restart TCP/IP Services. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded but the INET_ACP is not currently available for use. SS$_DUPLNAM Programming error. An attempt to bind a port that is already in use occurred. An attempt to bind the socket to an address and port failed. SS$_FILALRACC Programming error. IP address is already in use. An attempt to bind the socket to an address and port failed. SS$_INSFMEM Programming or system management error: Not enough resources to allocate new socket. SS$_ILLCNTRFUNC Programming error. Operation is not supported because of one of the following reasons: o Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. o An attempt was made to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function. SS$_IVADDR The specified IP address was not found, or an invalid port number and IP address combination was specified. Port 0 is not allowed with this function. SS$_IVBUFLEN Programming error. The socket option buffer has an invalid size. SS$_NOLICENSE Programming or system management error. The TCP/IP Services license is not present. SS$_NOOPER Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. Not enough privileges for the attempted operation for one of the following reasons: o Broadcasting an IP datagram was denied because the process does not have SYSPRV, BYPASS, or OPER privilege. o An attempt was made to use a reserved port number lower than 1024. o An operation accesses only processes that have SYSPRV or BYPASS privilege. o Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the ARP table. An attempt to show or delete an ARP table entry failed. SS$_NOSUCHNODE Programming or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found. SS$_PROTOCOL Programming error. The specified protocol type is not supported. SS$_SHUT The local or remote node is no longer accepting connections. 6 IO$_SETMODE|IO$M_READATTN The IO$_SETMODE|IO$M_READATTN function/modifier combination requests that an Attention AST be delivered to the requesting process when a data packet is received on the socket and there is no waiting read request. The Enable Read Attention AST function enables an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before the AST can occur again. The function is subject to AST quotas. Consider the following when using IO$M_READATTN: o There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For each enabled AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when an event occurs. o If an out-of-band (OOB) Attention AST is enabled, the OOB AST is delivered, regardless of the following: - An enabled Read Attention AST - The TCPIP$C_OOBINLINE socket option - A READ $QIO waiting for completion on the socket If the TCPIP$C_OOBINLINE option is set, then a waiting READ $QIO is completed and the OOB character is returned in the data stream. o If both an OOB AST and a Read Attention AST are enabled, only the OOB AST is delivered when an OOB character is received. o If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE socket option is set, a waiting READ $QIO completes and the OOB character is returned in the data stream. o If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE socket option is not set (clear), the Read Attention AST is delivered when an OOB character is received, regardless of whether a READ $QIO is waiting for completion. In this case, the OOB character is not returned in the data stream. Therefore, if the OOB character is the only character received, the READ $QIO does not complete. 7 Arguments p1 OpenVMS usage:ast_procedure type: procedure value access: call without stack unwinding mechanism: by reference To enable the AST, the p1 argument is the address of the Read Attention AST routine. To disable the AST, set p1 to 0. p2 OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value AST parameter to be delivered to the AST routine. p3 OpenVMS usage:access_mode type: longword (unsigned) access: read only mechanism: by value Access mode in which the AST is delivered. 7 Condition_Values_Returned SS$_ABORT Programming, INET management, or hardware error. The route entry already exists, so the attempt to add a route entry using the IO$_SETMODE function failed. SS$_ACCVIO Programming error. An attempt to access an invalid memory location or buffer occurred. SS$_BADPARAM Programming error. The parameter specified for a $QIO function was invalid for one of the following reasons: o An attempt to execute the IO$_SETMODE functions without specifying a device socket occurred. Instead, create a device socket by issuing a $QIO with the IO$_ SETMODE function and the proper parameters. o A socket option was specified incorrectly. SS$_DEVACTIVE INET management error. An attempt to change a static parameter was unsuccessful. If you need new parameters, restart TCP/IP Services. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded but the INET_ACP is not currently available for use. SS$_DUPLNAM Programming error. An attempt to bind a port already in use occurred so the operation to bind the socket to the address and port failed. SS$_FILALRACC Programming error. An attempt to bind the socket to an address that is already in use occurred and the operation failed. SS$_INSFMEM Programming or system management error. The system does not have enough resources to allocate new socket. SS$_ILLCNTRFUNC Programming error. Operation is not supported. o Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. o An attempt was made to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function. SS$_IVADDR Programming error. The specified IP address is not in the system, and an invalid port number or an invalid IP address combination was specified with an IO$_SETMODE function (a bind). o An attempt to bind the address failed because the IP address is not in the system, Port 0 and IP address 0 are not allowed, or Port 0 is not allowed when using an IO$_ACCESS function. o An attempt was made to make a permanent entry in the ARP table failed because of lack of space. Too many permanent entries. o An attempt was made to bind an IP socket (raw IP) when there are no interfaces defined in the system. o An attempt was made to bind an IP socket (raw IP) to a null INET address. SS$_IVBUFLEN Programming error. The socket option buffer has an invalid size. SS$_NOLICENSE Programming or system management error. The TCP/IP Services license is not present. SS$_NOOPER Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. Not enough privileges for the attempted operation. o Broadcasting an IP datagram was denied because the process does not have SYSPRV, BYPASS, or OPER privilege. o An attempt was made to use a reserved port number lower than 1024. o An operation accesses only processes that have SYSPRV or BYPASS privilege. o Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. An Internet address is not in the ARP table. An attempt to show or delete an ARP table entry failed. SS$_NOSUCHNODE Programming error or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found. SS$_PROTOCOL Programming error. The specified protocol type is not supported. SS$_SHUT The local or remote node is no longer accepting connections. 6 IO$_SETMODE|IO$M_WRTATTN The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_ WRTATTN is Enable Write Attention AST) requests that an Attention AST be delivered to the requesting process when a data packet can be queued to the socket. For TCP sockets, this occurs when space becomes available in the TCP transmit queue. The Enable Write Attention AST function enables an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before the AST can occur again. The function is subject to AST quotas. There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For example, for each enabled AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when the event occurs. You can use the TCP/IP management command SHOW DEVICE_SOCKET to display information about the socket's characteristics, options, and state. 7 Arguments p1 OpenVMS usage:ast_procedure type: procedure value access: call without stack unwinding mechanism: by reference To enable the AST, the p1 argument is the address of the Write Attention AST routine. To disable the AST, p1 is set to 0. p2 OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value AST parameter to be delivered to the AST routine. p3 OpenVMS usage:access_mode type: longword (unsigned) access: read only mechanism: by value Access mode in which the AST is delivered. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The route specified with the IO$_SETMODE function already exists. Therefore, the operation failed. SS$_ACCVIO Programming error. An attempt to access an invalid memory location or buffer occurred. SS$_BADPARAM Programming error. The parameter specified for the $QIO I/O function was invalid for one of the following reasons: o An attempt was made to execute the IO$_ SETMODE functions without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_ SETMODE function and the proper parameters. o A socket option was specified incorrectly. SS$_DEVACTIVE INET management error. You attempted to change the static parameters. If you need new parameters, restart TCP/IP Services. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded but the INET_ACP is not currently available for use. SS$_DUPLNAM Programming error. Port that is being bound is already in use. An attempt to bind the socket to an address and port failed. SS$_FILALRACC Programming error. Because the IP address is already in use, an attempt to bind the socket to an address and port failed. SS$_INSFMEM Programming or system management error. There are not enough resources to allocate a new socket. SS$_ILLCNTRFUNC Programming error. An attempt was made to execute an IO$_SETMODE function that required a socket, but the device did not have one. Instead, create a socket and issue the function. SS$_IVADDR Programming error. An invalid port number and IP address combination was specified with the IO$_SETMODE bind function. This caused the operation to fail for one of the following reasons: o An illegal combination of Port 0 and IP address 0 was specified. o An attempt was made to make a permanent entry in the ARP table and the operation failed because of lack of space. There are too many permanent entries. o An attempt was made to bind a raw IP socket when there were no interfaces defined in the system. o An attempt was made to bind a raw IP socket to a null IP address. SS$_IVBUFLEN Programming error. An invalid size was specified for the socket option buffer. SS$_NOLICENSE Programming or system management error. The TCP/IP Services license is not present. SS$_NOOPER Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege. SS$_NOPRIV Programming or INET management error. The operation failed for one of the following reasons: o An attempt was made to broadcast an IP datagram for a process without having SYSPRV, BYPASS, or OPER privilege. o An attempt was made to use a reserved port number lower than 1024. o An attempt was made to access a process without having SYSPRV or BYPASS privilege. o An attempt was made to use raw IP on a socket that is not a privileged socket. To do this, the process must have SYSPRV or BYPASS privilege. SS$_NOSUCHDEV Programming error or INET management error. An attempt was made to show or delete an entry in the ARP table. However, because the IP address was not in the ARP table, the operation failed. SS$_NOSUCHNODE Programming error or INET management error. An attempt was made to delete a route from the routing information table (RIT). However, because the route was not found in the RIT, the operation failed. SS$_PROTOCOL Programming error. The specified protocol is not supported. SS$_SHUT The local or remote node is no longer accepting connections. 6 IO$_WRITEVBLK The IO$_WRITEVBLK function transmits data from the specified user buffers to an Internet host. Use both p1 and p2 arguments to specify a single user buffer. Use the p5 argument to specify multiple buffers. For connection-oriented protocols, such as TCP, if the socket transmit buffer is full, the IO$_WRITEVBLK function is blocked until the socket transmit buffer has room for the user data. For connectionless-oriented protocols, such as UDP and raw IP, the user data is transmitted in one datagram. If the user data is greater than the socket's transmit quota, the error code (SS$_ TOOMUCHDATA) is returned. Related Functions The equivalent Sockets API functions are send(), sendto(), sendmsg(), and write(). 7 Arguments p1 OpenVMS usage:buffer type: vector byte (unsigned) access: read only mechanism: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference The address of the buffer containing the data to be transmitted. The length of this buffer is specified by the p2 argument. p2 OpenVMS usage:buffer_length type: quadword unsigned (Alpha and I64); longword unsigned (VAX) access: read only mechanism: (Alpha and I64) by 64-bit value (VAX) by 32-bit value The length (in bytes) of the buffer containing data to be transmitted. The address of this buffer is specified by the p1 argument. p3 OpenVMS usage:socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor The remote port number and IP address of the message destination. The p3 argument is the address of an item_list_2 descriptor pointing to the socket address structure containing the remote port number and IP address. p4 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Longword of flags to specify attributes for this write operation. The following table lists the available write flags: Write Flag Description TCPIP$C_MSG_OOB Writes an out-of-band (OOB) byte. TCPIP$C_MSG_ Sends message directly without routing. DONTROUTE TCPIP$C_MSG_NBIO Completes the I/O operation and returns an error if a condition arises that would cause the I/O operation to be blocked. (Similar to using IO$M_NOWAIT.) p5 OpenVMS usage:buffer_list type: vector byte (unsigned) access: read only mechanism: (Alpha and I64) by 32- or 64-bit descriptor-fixed-length descriptor (VAX) by 32-bit descriptor-fixed-length descriptor Input buffer list describing one or more buffers containing the data to be transmitted. The p5 argument is the address of a descriptor pointing to a input buffer list. Buffers are transmitted in the order specified by the input buffer list. The transfer-length value returned in the I/O status block is the total number of bytes transferred from all buffers. If you use the p1 and p2 arguments, do not use the p5 argument; they are mutually exclusive. 7 Function_Modifiers IO$M_EXTEND Allows the use of extended modifiers with BSD Version 4.4. Valid only for datagram sockets (UDP or raw IP); ignored for TCP. IO$M_INTERRUPT Sends an OOB message. IO$M_NOWAIT Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code. When using this function modified, always check the message length in the IOSB to ensure that all data is transferred. IO$_WRITEVBLK returns a success status even if data is only partially transferred. 7 Condition_Values_Returned SS$_ABORT Programming error, INET management error, or hardware error. The execution of the I/O was aborted. SS$_ACCVIO Programming error. An attempt was made to access an invalid memory location or buffer. SS$_BADPARAM Programming error. An I/O operation was specified using an invalid parameter. o An attempt was made to execute an IO$_WRITEVBLK function without specifying a device socket. First create a device socket by issuing an IO$_SETMODE function and the proper arguments. o An attempt was made to issue an IO$_WRITEVBLK function that did not specify a correct buffer address (p1 or p5 is null). o An attempt was made to issue an IO$_WRITEVBLK that specifies an invalid vectored buffer (p5 specifies an invalid address descriptor). SS$_CANCEL The I/O operation was canceled by the $CANCEL system service. SS$_DEVINTACT The network driver was not started. SS$_DEVNOTMOUNT The network driver is loaded, but the INETACP is not currently available for use. SS$_EXQUOTA Returned when process resource mode wait is disabled. There is no Internet request packet (IRP) available for completing the request. Increase the buffered I/O quota. SS$_FILALRACC Programming error. o IP address is already in use. An attempt was made to bind the socket to an address but the port failed. o IP protocol (raw socket). An attempt was made to specify a remote socket address with an IO$_WRITEVBLK function, while an IP address was already specified with an IO$_ACCESS function. o UDP/IP protocol. An attempt was made to specify a remote socket address with an IO$_WRITEVBLK function, while an IP address was already specified with the IO$_ACCESS function. SS$_ILLCNTRFUNC Programming error. Unsupported operation on the protocol (UDP or TCP). SS$_INSFMEM Insufficient system dynamic memory to complete the operation. SS$_IVADDR Programming error. The specified IP address is not in the system, and an invalid port number or an IP address combination was specified with an IO$_WRITEVBLK operation. o An attempt to bind the socket failed because the INET address is not in the system, Port 0 and IP address 0 are not allowed, or Port 0 is not allowed with an IO$_WRITEVBLK function. o An attempt to get an interface IP address, broadcast mask, or network mask failed. o A send request was made on a datagram- oriented protocol, but the destination address is unknown or not specified. SS$_IVBUFLEN Programming error. o The size of the buffer for an I/O function is insufficient. o An attempt was made to issue an IO$_WRITEVBLK function that specifies a correct buffer address (p1 valid) but does not specify a buffer length (p2 is null). SS$_LINKDISCON Notification. Connection completion return code. The virtual circuit (TCP/IP) was closed at the initiative of the peer. The application must stop sending data and must either shut down or close the socket. SS$_PROTOCOL Programming error. The address family of the remote address specified with an IO$_WRITEVBLK function is not supported (UDP or TCP). The address family should be either the TCPIP$C_AF_INET or the TCPIP$C_AF_INET6 address family. SS$_NOLINKS Programming error. The socket was not connected (TCP), or an INET port and address were not specified with an IO$_ACCESS (UDP). o An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (raw IP). o An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (UDP). o An attempt was made to disconnect a socket that is not connected, or an attempt was made to issue an IO$_WRITEVBLK function on an unconnected socket (TCP). SS$_SHUT The local or remote node is no longer accepting connections. SS$_SUSPENDED The system detected a condition that might cause the operation to block. SS$_TIMEOUT Programming error, INET management error, or hardware error. o A TCP/IP connection timed out after several unsuccessful retransmissions. o On a TCP socket where KEEPALIVE is set, the connection was idle for longer than the timeout interval. The default is 10 minutes. SS$_TOOMUCHDATA Programming or INET management error. The message size was too large. o An IP packet that is broadcast cannot be fragmented. o The Not Fragment IP flag was set and the IP datagram was too large to be sent without being fragmented. o Internal error. The length of the Ethernet datagram does not allow enough space for the minimum IP header. o The message to be sent on a UDP or raw IP socket is larger than the socket buffer high water allows. For more information, see IOCTL Requests. o An attempt was made to send or receive more than 16 buffers specified with the p5 argument. SS$_UNREACHABLE Communication status. The remote host is currently unreachable. This indicates a hardware error. The data link adapter detected an error and shut itself off. The TCP/IP Services software is waiting for the adapter to come back on line. 5 TELNET_Port_Driver_$QIO_Interface The TELNET port driver (TNDRIVER) provides terminal session support for TCP streaming connections using the RAW, NVT, RLOGIN, and TELNET protocols. Either a remote device or an application can be present at the remote endpoint of the connection. A user program can manage a TELNET connection with the standard OpenVMS $QIO system service by using the IO$_TTY_PORT and IO$_ TTY_PORT_BUFIO I/O function codes. 6 Interface_Definition The following definitions are used by the interface. The symbols are defined in SYS$LIBRARY:TNIODEF.H. 7 Item_List_Codes The following table describes the symbols used with the p5 parameter. Maximum Item Code Size Description TN$_ACCPORNAM 64 Access port name string. When written, the string's length is determined by the item_length field. The value of item_length should not be more than 63 bytes. When read, the string is returned in ASCIC format (the first byte contains the string's length), so a size of 64 is appropriate. TN$_ 4 Characteristics mask. This longword CHARACTERISTICS contains a bit mask of the device's characteristics read or to be written. (See Characteristic Mask Bits for a table that describes the characteristic mask bits.) TN$_CONNECTION_ 4 Reconnection attempts. This item ATTEMPTS is the number of unsuccessful reconnection attempts which have been made on a reconnectable device. The value will be reinitialized when a successful connection is made. This item is read only. TN$_CONNECTION_ 4 Minimum time (in seconds) before INTERVAL reconnection attempts. TN$_CONNECTION_ 4 Current time (in seconds) since TIMEOUT the last reconnection attempt. This item is read only. TN$_DATA_HIGH 4 Maximum amount of output data (in bytes) buffered at the network port. This number does not affect the amount of data buffered within the socket. TN$_DEVICE_UNIT 4 Terminal device unit number. When written, this value must be between 1 and 9999. TN$_IDLE_INTERVAL 4 Maximum idle time (in seconds) allowed before a connection is to be broken. Connections are not broken if the device is stalled. TN$_IDLE_TIMEOUT 4 Current time (in seconds) since last output on the terminal. This item is read only. TN$_LOCAL_ADDRESS 32 Local sockaddr of the active connection. When written, the value of item_length determines the size of the sockaddr. Note that the sockaddr is in BSD Version 4.4 format, which includes a sockaddr size field. (C programs should be compiled with the _SOCKADDR_LEN symbol defined.) This item is read only. TN$_NETWORK_ 64 Name of the network pseudodevice DEVICE_NAME currently bound to the terminal. When read, the data is returned in ASCIC format (the first byte contains the string's length). This item is read only. TN$_PROTOCOL 4 Session protocol. (See the table in Protocol Types.) TN$_REMOTE_ADDRESS 32 Remote peer's sockaddr of the active connection. Note that the sockaddr is in BSD Version 4.4 format, which includes a sockaddr size field. The size of the sockaddr should be determined from this field. This item is read only. TN$_SERVICE_TYPE 4 Class of terminal service. (See the table in Service Types.) TN$_STATUS 4 Current device and session status. This item is read only. 7 Characteristic_Mask_Bits The following table describes the characteristic mask bits used with the p5 parameter. Characteristic Description TN$M_AUTOCONNECT The device supports automatic connect/reconnect. TN$M_LOGIN_ON_ Initiate a login when the TELNET device is DASSGN deassigned. This characteristic requires the BYPASS or SYSNAM privilege or executive or kernel mode calls. TN$M_LOGIN_TIMER Used in conjunction with TN$M_LOGIN_ON_DASSGN, this bit indicates that the login completion timer applies. If the TN device fails to login within 60 seconds, the connection will be broken and the device deallocated. This characteristic requires the BYPASS or SYSNAM privileges or executive or kernel mode calls. TN$M_PERMANENT_ The TELNET device is to remain until UCB explicitly deleted. TN$M_RETAIN_ON_ The TELNET device is not to be deleted upon DASSGN the deassignment of the last channel to this device. This condition is cleared on this last deassignment, so that a subsequent assign and deassign will result in the device being deleted. TN$M_VIRTUAL_ When logging in under this device, a virtual TERMINAL terminal is to be created by TTDRIVER. 7 Protocol_Types The following table describes the protocol types used with the p5 parameter. Protocol Type Description TN$K_PROTOCOL_ There is no explicit protocol for this UNDEFINED session. Data is transmitted and received on the socket without any interpretation. This is a raw connection. TN$K_PROTOCOL_NVT Network Virtual Terminal (NVT) protocol. The protocol understands basic session control but does not include the options negotiation present in the TELNET protocol. TN$K_PROTOCOL_RLOGIN BSD Remote Login protocol. This simple protocol provides some special control character support but lacks the architecture independence of the NVT and TELNET protocols. TN$K_PROTOCOL_TELNET TELNET protocol. Including the basic NVT protocol, TELNET adds support for options negotiation. This can provide an enhanced terminal session depending upon the client and server involved. 7 Service_Types The following table describes the service type codes used with the p5 parameter. Service Type Description TN$K_SERVICE_NONE The service type is not currently known. TN$K_SERVICE_ The service is an incoming connection. INCOMING TN$K_SERVICE_ The service is an outgoing connection. OUTGOING 6 Passing_Parameters_to_the_TELNET_Port_Driver The IO$_TTY_PORT function is used to pass $QIO parameters through the terminal driver to the TELNET port driver. The actual subfunction is encoded as an option mask and may be: o IO$M_TN_STARTUP - Bind socket to a TELNET terminal. o IO$M_TN_SHUTDOWN - Unbind socket from a TELNET terminal. 5 IO$_TTY_PORT|IO$M_TN_STARTUP Bind socket to a TELNET terminal. This subfunction will bind a created (connected) socket to a TELNET terminal device. 6 Arguments p1 OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value The p1 argument contains the channel number of the socket over which the TELNET session is to be established. p2 OpenVMS usage:protocol_number type: longword (unsigned) access: read only mechanism: by value The p2 argument contains the protocol selection. p3 OpenVMS usage:characteristics_mask type: longword (unsigned) access: read only mechanism: by value The p3 argument specifies a mask of characteristics to apply against the connection. See the table in Item List Codes under Interface Definition help for possible values. 6 Description The IO$M_TN_STARTUP subfunction allows the application to communicate over a socket using the terminal driver QIO interface. Note that incoming and outgoing data is processed by the terminal driver, and that the terminal's characteristics may affect the format of the data. Be aware that by default, the terminal will echo incoming data back to the sender. Once the subfunction completes, the application is free to perform all terminal QIO functions on the connection. While the socket is bound to a terminal device, it will process neither the IO$_READxBLK nor the IO$_WRITExBLK function, and will return the error SS$_DEVINUSE. 6 Condition_Values_Returned SS$_IVCHAN Programming error. The specified channel is not valid. SS$_IVMODE Programming error. The access mode of the channel is more privileged than the access mode of the terminal's channel. SS$_NOPRIV Programming error. The TN$M_LOGIN_ON_ DASSGN characteristic was specified in a characteristics mask from a $QIO in USER or SUPERVISOR mode without either the BYPASS or SYSPRV privilege. SS$_NOTNETDEV Programming error. The specified channel is an assignment to a non-BG device. SS$_PROTOCOL Programming error. The specified protocol number is not valid, or the network is not available. 5 IO$_TTY_PORT|IO$M_TN_SHUTDOWN Unbind socket from a TELNET terminal. This subfunction will unbind a previously bound socket-terminal connection. 6 Arguments p1 OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by value The p1 argument contains the channel number of the socket to establish the TELNET session. 6 Description The IO$M_TN_SHUTDOWN subfunction allows the application to break a previously bound socket-terminal connection (created with IO$M_ TN_STARTUP). The channel must be from an assignment to the same network pseudodevice in the socket-terminal connection. Upon completion, the application retains the assignments to the connection and the TELNET terminal, but they are no longer related. Any subsequent IO$_READxBLK or IO$_WRITExBLK function on the socket channel will no longer return the error SS$_DEVINUSE. 6 Condition_Values_Returned SS$_IVCHAN Programming error. The specified channel is not valid. SS$_IVMODE Programming error. The access mode of the channel is more privileged than the access mode of the terminal's channel. SS$_NOTNETDEV Programming error. The specified channel is an assignment to a non-BG device. SS$_DEVREQERR Programming error. The device on the channel does not match the device in the socket- terminal connection. 6 Buffered_Reading_and_Writing_of_Item_Lists The IO$_TTY_PORT_BUFIO function is used to pass $QIO parameters through the terminal driver to the TELNET port driver. IO$_TTY_ PORT_BUFIO differs from IO$_TTY_PORT in that certain subfunctions accept buffered item lists for reading or writing parameters to the terminal device. o IO$M_TN_SENSEMODE - Read device parameters. o IO$M_TN_SETMODE - Write device parameters. The subfunctions of IO$_TTY_PORT_BUFIO accept an item list for input or output. Subfunction Item List shows the format of this item list. The item list is terminated with an item_code and item_length, both of which are zero. The subfunctions of IO$_TTY_PORT_BUFIO can be combined into a single $QIO. For example, the IO$M_TN_SETMODE and IO$M_TN_ CONNECT can be combined to set the device's parameters and then to attempt to make a connection. The subfunctions are performed in the following order: 1. IO$M_TN_SETMODE 2. IO$M_TN_CONNECT 3. IO$M_TN_SENSEMODE 4. IO$M_TN_DISCON NOTE Certain items are read only (IO$M_TN_SENSEMODE) and cannot be written (IO$M_TN_SETMODE). Normally, attempting to write such items would result in the error SS$_BADATTRIB. However, if a combination operation (IO$M_TN_SENSEMODE|IO$M_TN_ SETMODE) is being performed, these items will not result in an error. Rather, the items will be ignored in the IO$M_ TN_SETMODE processing, and the $QIO will continue with IO$M_ TN_SENSEMODE processing, returning the information that the item specifies. 6 IO$_TTY_PORT_BUFIO|IO$M_TN_SENSEMODE Read device parameters. 7 Arguments p5 OpenVMS usage:item_list_2 type: vector byte (unsigned) access: read only mechanism: by reference The p5 argument is the address of an item list that contains a summary of information to be read from the device. 7 Description The IO$M_TN_SENSEMODE subfunction of IO$_TTY_PORT_BUFIO is used to read the parameters associated with a device. 7 Condition_Values_Returned SS$_BADATTRIB Programming error. The item code within the list is not valid. This could be because of its code, an attempt to write a read-only parameter, or inappropriate size. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_IVBUFLEN Programming error. The length of the specified item is not acceptable. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_NOPRIV Programming error. An item that requires a privilege which the requestor does not have is present in the item list. The address of the item's buffer is returned in the second longword of the I/O status block. 6 IO$_TTY_PORT_BUFIO|IO$M_TN_SETMODE Write device parameters. 7 Arguments p5 OpenVMS usage:item_list_2 type: vector (byte unsigned) access: read only mechanism: by reference The p5 argument is the address of an item list that contains a summary of information to be written to the device. 7 Description The IO$M_TN_SETMODE subfunction of IO$_TTY_PORT_BUFIO is used to write the parameters associated with a device. 7 Condition_Values_Returned SS$_BADATTRIB Programming error. The item code within the list is not valid. This could be because of its code, an attempt to write a read-only parameter, or inappropriate size. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_DUPLNAM Programming error. An attempt to set the device's unit number via the TN$_DEVICE_UNIT item has failed because that specified unit number was already present. SS$_IVBUFLEN Programming error. The length of the specified item is not acceptable. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_NOPRIV Programming error. An item that requires a privilege which the requester does not have is present in the item list. The address of the item's buffer is returned in the second longword of the I/O status block. 2 FINGER For displaying information about users on remote systems and your local system, TCP/IP Services includes the FINGER utility. For example, you can use the FINGER utility to determine which users are logged on to a system or to refresh your memory about the correct login name to use before using FTP or another service to connect to an account on a remote host. The FINGER listing can include such information as: o User name o Account name o Program the user is running o User's home directory o User's plans, activities, and other information o User's project The FINGER software must be enabled on your local OpenVMS host (see your system manager). If FINGER has not been started, then attempts to use the FINGER command might cause an error message because of missing privileges. You must start the utility before attempting to use it. 3 User_Requirements Use the following rules for command syntax and wildcards when you enter FINGER command lines. o Wildcards - Wildcards are not accepted for OpenVMS hosts but may be valid for some UNIX hosts. o Qualifiers - Qualifiers to the FINGER command must follow immediately after the command verb and must precede the user or host name. If the qualifier follows the user or host name, the FINGER utility interprets the qualifier as a user name. For example, in the following command, the qualifier /FULL incorrectly appears after the user specification. As indicated by the last line in the display, the FINGER server interprets /FULL as a user login name. $ FINGER ROLLINS /FULL Username Program Login Term/Location ROLLINS $ Mon 15:02 64626::ROLLINS Login name: ROLLINS In real life: Professor Rollins Account: RES9 Directory: WORK1$:[ROLLINS] Last login: Tue 3-MAR-2002 09:05:29 Unread mail: 25 Project: Homeopathic medicine/Silica No Plan. Login name: /FULL In real life: ??? o User Information - To display information about all users on a remote host, enter the FINGER command followed by the host name (FINGER @hostname). To display more detailed information about a particular user, specify the user name with the host name (format FINGER username@hostname). To display information about all users on your local host, enter the FINGER command without specifying a host name. To display detailed information about a specific user on your local host, enter the FINGER command followed by the user name. 3 Examples 1. To display brief information about all users on a host, use the FINGER command with the host name only, in the format @hostname. If you use the FINGER command alone (without specifying a host name), you receive brief information about all users on your local system. The following example shows how to display brief information about all users on remote host SCIENCE: $ FINGER @SCIENCE [science.ucd.edu] Username Program Login Term/Location BRADY $ Thu 07:50 dialin_706_101.ucd.lab.edu CORRIT $ Tue 13:30 64334::CORRIT DAVE MAIL Mon 15:02 64334::DAVE DAWSON $ Thu 14:57 FLOYD $ Mon 17:00 KITT TPU Mon 16:57 62555::KITT MIRTH $ Wed 16:04 UCDVAX::MIRTH NATALIE $ Tue 09:23 64222::NATALIE RAPSONG $ Mon 18:50 64442::RAPSONG 2. To display details about one or more users on a remote host, specify the user name or a list of user names, including the host name with each user name, as shown in the examples that follow. $ FINGER HOWE@BEARINGS [bearings.us.beacorp.com] Username Program Login Term/Location HOWE MAIL Mon 15:02 84640::HOWE Login name: HOWE In real life: Abe Howe Account: INVENT Directory: DISK$1:[HOWE] Last login: Tue 3-MAR-2002 10:15:39 No unread mail Project: Inventory No Plan. 3. This example shows the default display for the FINGER/CLUSTER command. $ FINGER/CLUSTER Username Node Program Login Term/Location ANND UCDAXP $ Mon 17:00 BRADY UCDAXP $ Thu 07:50 dialin_101.ads.com CALLING UCDALP RTPAD Thu 14:50 CALLING UCDAXP $ Thu 14:57 CURREN UCDAXP $ Tue 13:30 84051::CURREN DOBB UCDWON TCPIP$FINGER Mon 11:50 GILBERT UCDVAX MAIL Thu 14:34 pcgil.admin.ucd.edu IMMIN UCDALP $ Wed 16:21 BIXBY::IMMIN KITT UCXAXP $ Mon 16:57 62555::KITT KITTEL UCXALP $ Thu 14:12 AGGIE::KITTEL LEVINE UCDUNI DECW$SESSION Thu 10:50 LEVINE UCDALP TCPIP$UCP Thu 10:30 llevine.ads.com MILLLER UCDALP TCPIP$FINGER Thu 15:00 AGGIE::MILLER MIRTH UCDVAX $ Tue 17:09 MIRTH UCDVAX RTPAD Mon 17:27 NATALIE UCDAXP $ Tue 09:23 64222::NATALIE POFF UCXAXP $ Tue 02:42 AGGIE::POFF RAPSONG UCDAXP $ Mon 18:50 64442::RAPSONG TIBBS AGGIE $ Tue 20:43 UCXAXP::TIBBS 4. This example displays each user's real name and every login to cluster members by including the /FULL qualifier. $ FINGER/CLUSTER/FULL Username Real Name Node Program Login Term/Location ANND Ann Darin UCDAXP $ Mon 17:00 UCDAXP $ Tue 11:51 BRADY Robert Brady UCDAXP $ Thu 07:50 dialin_101.ads.com UCDWON $ Fri 08:31 CALLING Alvin Calling UCDALP RTPAD Thu 14:50 UCDAXP $ Thu 14:57 CURREN Steve Curren UCDAXP $ Tue 13:30 84051::CURREN UCDVAX $ Tue 14:20 DOBB Barry Dobb UCDWON TCPIP$FINGER Mon 11:50 UCDAXP $ Wed 09:20 GILBERT Joanne Gilbert UCDVAX MAIL Thu 14:34 pcgil.ads.com IMMIN Armen Immin UCDALP $ Wed 16:21 BIXBY::IMMIN KITT Evelyn Kitt UCXAXP $ Mon 16:57 62555::KITT UCDALP SEARCH Mon 16:43 62555::KITT KITTEL Herb Kittel UCXALP $ Thu 14:12 AGGIE::KITTEL LEVINE Larry Levine UCDUNI DECW$SESSION Thu 10:50 UCDALP TCPIP$UCP Thu 10:30 slevine.ads.com MILLLER Paul Miller UCDALP TCPIP$FINGER Thu 15:00 AGGIE::MILLER MIRTH Phil Anson UCDVAX $ Tue 17:09 UCDVAX RTPAD Mon 17:27 NATALIE Natalie Beardsley UCDAXP $ Tue 09:23 64222::NATALIE POFF Pamela Offred UCXAXP $ Tue 02:42 AGGIE::POFF RAPSONG Aaron Feller UCDAXP $ Mon 18:50 64442::RAPSONG TIBBS Eugene Tibbs AGGIE $ Tue 20:43 UCXAXP::TIBBS 2 FTP FTP - the File Transfer Protocol - allows you to connect to a remote host and perform the following actions: o Transfer files between your local host and the connected remote host o Append local files to remote host files o Delete and rename files on the remote host o Create, delete, and rename directories on the remote host o View the contents of directories and files on the remote host FTP also allows you to set and display the default working directory on the remote host as well as on your local host, and to customize FTP command processing. You can also use RCP to copy files. For more information on RCP, see Remote_Commands. To use the Secure Shell (SSH) for file transfers, refer to the HP TCP/IP Services for OpenVMS Guide to SSH. To use FTP, you need the following: o A user account on the OpenVMS system with access to TCP/IP Services for OpenVMS o One of the following: - A user account on the remote FTP host - Access to the remote host's ANONYMOUS user account 3 Command_Summary To use FTP, enter the commands summarized below. For complete descriptions (including UNIX equivalents) of each command, type the following command: $ FTP FTP>HELP Command Description Starting and Exiting (At the DCL Prompt) FTP Invokes FTP. FTP remote_host Invokes FTP and establishes a connection to a remote host. Starting and Exiting (At the FTP> Prompt) CONNECT Establishes a connection to a remote host. DISCONNECT Closes the connection with the remote host. EXIT Closes the connection with the remote host Ctrl/Z and exits FTP. Sending Commands to the Remote Host APPEND Appends a local file to a remote file. CREATE/DIRECTORY Creates a remote directory. DELETE Deletes remote files. DIRECTORY Lists remote file names and related information. GET Copies files from the remote host to the local host. LOGIN Logs you in to a remote host. PUT Copies files from the local host to the remote host. RENAME Renames remote files. SET DEFAULT Sets the remote working directory or the local working directory. SHOW DEFAULT Displays the name of the current working directory. VIEW Displays the contents of a file on the current output device. Suspending FTP to Return to DCL Prompt SPAWN Suspends FTP to create a subprocess at the local DCL prompt. Customizing Your Session's Environment DISABLE LOG Disables the display of all the protocol commands sent to the remote host. DISABLE PARSE Disables the expansion of file names. DISABLE Disables the sending of the FTP protocol PORT_COMMAND PORT command. DISABLE REPLY Disables the display of all responses from the remote host. DISABLE Disables the display of # for each 1K bytes TRANSFER_VERIFICATION of data transferred. DISABLE Disables the special OpenVMS-to-OpenVMS VMS_PLUS transfer mode. ENABLE LOG Enables the display of all protocol commands sent to the remote host. ENABLE PARSE Enables the expansion of file names. ENABLE Enables the sending of the FTP protocol PORT_COMMAND PORT command. ENABLE REPLY Enables the display of all responses from the remote host. ENABLE Enables the display of the pound sign (#) TRANSFER_ for each 1K bytes of data transferred. VERIFICATION ENABLE Enables the OpenVMS-to-OpenVMS transfer VMS_PLUS mode. HELP Invokes help. QUOTE Sends FTP commands to the remote host without local interpretation. SET TYPE Defines the data representation for file transfers. SHOW STATUS Displays the current FTP parameter settings and, if you have an open connection, the name of the connected host. SPAWN Starts a subprocess at the DCL prompt. 3 FTP_Conventions Use the following rules for command syntax, quotation marks, and wildcard characters when you type FTP command lines. o Command syntax With the FTP command and most of the commands at the FTP prompt, you can use either DCL or UNIX command syntax. For example, the DCL DIRECTORY and the UNIX ls commands produce the same results o Quotation marks When you communicate with a non-OpenVMS host, you might need to enclose the following within quotation marks: o UNIX path names o UNIX file names with slashes o Lowercase or mixed-case host names, user names, passwords, file names, and command lines As shown in the following example, enclose UNIX path names with quotation marks: FTP> put MY.DOC "/usr/users/evt/my.doc" 200 PORT command successful. 150 Opening ASCII mode data connection for /usr/users/evt/mydoc (130.180.4.8,1789). 226 Transfer complete. local: WORK1$:[VANA]MY.DOC;2 remote: /usr/users/evt/my.doc 289 bytes sent in 00:00:00.01 seconds (20.15 Kbytes/s) o Wildcards You can use wildcards in the following FTP commands: DELETE, DIRECTORY, GET, PUT, MGET, MPUT, MDELETE, and MLS. The wildcard characters recognized by FTP include the following: o The percent sign (%) to represent an individual character o The question mark (?) to represent an individual character o The asterisk (*) to represent multiple characters If any of these characters are part of a file name but are not used as a wildcard, you can disable recognition of these characters as wildcards by either enclosing the file name in quotation marks or using the DISABLE PARSE command. o Qualifiers In DCL command lines, you can place a command qualifier anywhere on the command line. It is a good practice to follow the OpenVMS recommendation of placing the qualifier after the command name. 3 Starting_FTP You can start an FTP session in any of the following ways: o At the DCL prompt, enter the FTP command and specify a remote host. o At the DCL prompt, enter the FTP command with no parameters. At the FTP prompt, enter the CONNECT or open command, specifying a remote host. o By using the /FTP qualifier on the DCL commands COPY and DIRECTORY. o Invoke and use FTP from a command procedure You must connect to a remote host before you can enter an FTP command that affects or displays files on the remote host. You can invoke FTP and, without first connecting to a remote host, enter the FTP commands that customize the FTP environment. When you establish an FTP connection, the remote user name defaults to your user name on the local system. If you have a different user name on the remote system, do one of the following: o On the FTP command line, enter the /USERNAME qualifier. o At the user name prompt, type your remote user name. For example: $ FTP SITE1 220 site1.midwest.billing.bench.com FTP server (Version 5.0) ready Connected to SITE1.midwest.billing.bench.com. Name (SITE1:antel): crowe 331 Username CROWE requires a Password Password: 230 User logged in If your connection is with another OpenVMS host, it executes your LOGIN.COM procedure. You can use your LOGIN.COM command procedure to customize the environment for your FTP sessions. 4 Examples The following example connects to host XENO using the FTP command: $ FTP XENO /USER="bennings" /PASSWORD="keysimpl" 220 xeno FTP Server (UNIX Version 5.60) ready Connected to XENO.site1.acctg.com. 230 User logged in FTP> In the following example, user dave invokes FTP and connects to UNIX host sanfran using the CONNECT command: $ FTP FTP> CONNECT SANFRAN 220 sanfran.golden.com FTP server (UNIX Version 5.60) ready Connected to sanfran.golden.com. Name (sanfran:dave): 331 Password required for dave Password: 230 User logged in FTP> 3 Anonymous_FTP Anonymous user access, also called Anonymous FTP, lets you make an FTP connection to a remote host by specifying the name ANONYMOUS (or another name defined by the system manager). With Anonymous FTP, you do not need: o A registered user account on the remote host o To use your own user account, if you have one o To supply a password With Anonymous FTP, you can perform the following actions: o View remote directories - View the guest and public directories with the FTP command DIRECTORY. - If set up, the public directory called GUEST$PUBLIC has general bulletin-board information. It contains files of interest to FTP users. o Copy files - Enter GET and PUT commands to copy files to and from GUEST$PUBLIC. - The public area is read-only. You can enter the GET command to copy files from the remote host to your local system. Optionally, there may be an ANONYMOUS$USER directory where you can perform the following actions: - Delete files - Create directories - Delete directories - Rename files - Rename directories The system manager sets up the access restrictions for Anonymous FTP that determine the availability of features. NOTE GUEST$PUBLIC and ANONYMOUS$USER are devices names for directories that may be set up by the system manager. See the HP TCP/IP Services for OpenVMS Management manual for more information. 4 Examples In the following example, UNIX user williams uses Anonymous FTP to connect to the ANONYMOUS account on OpenVMS host TRACTPLAN. Rather than prompt for a password, TRACTPLAN asks for the user name. % ftp tractplan Connected to tractplan.green_dev.org. 220 tractplan FTP Server (Version 5.1) ready Name (tractplan:williams): anonymous 331 Guest login ok, send ident as password Password: williams@tractplan.edu 230 Guest login ok, access restrictions apply 3 Exiting_FTP You can end an FTP session and return to the DCL prompt by entering the EXIT, quit, or bye commands or by pressing Ctrl/Z. The following examples close a connection with the remote host and exit FTP. FTP> EXIT 221 Goodbye. $ FTP> quit 221 Goodbye. $ To close a connection and remain at the FTP prompt, use the DISCONNECT or close command. 4 Examples The following examples show how to close a connection, if one is open, and remain at the FTP prompt for you to continue using FTP. FTP> DISCONNECT 221 Goodbye. FTP> FTP> CLOSE 221 Goodbye. FTP> 3 Viewing_Remote_Directories Use the DIRECTORY command to list the files and associated information in remote directories. For example, the following command lists the files in the default directory on a remote UNIX host (assuming the user already has connected to the remote host): FTP> DIRECTORY 200 PORT command successful 150 Opening ASCII mode data connection for /bin/ls (130.180.4.8,1312) total 6303 -rw-rw-r-- 1 milgrom users 1 Jan 9 2002 #UNTITLED# -rw------- 1 milgrom users 4 Apr 11 2002 .Xauthority -rwxr-xr-x 1 milgrom users 1499 Feb 3 2002 .cshrc drwxr-xr-x 11 milgrom users 8192 Jan 9 2002 .dt -rwxr-xr-x 1 milgrom users 3970 Dec 13 2002 .dtprofile) 3 Default_Directory During an FTP session, you can display or change the current default directory either on the remote host or on your local host. To display the default (working) directory on the remote host, use the SHOW DEFAULT command, as in the following example: FTP> SHOW DEFAULT 257 "/usr/users" is the current directory. To display the working directory on the local host, use the SHOW DEFAULT command with the /LOCAL qualifier, as in the following example: FTP> SHOW DEFAULT/LOCAL Local directory is DISK$6:[MANAGER]. To change the default directory on the remote host, use the SET DEFAULT command. The following example shows how to change the default directory on a remote UNIX host to /usr/users/robert: FTP> SET DEFAULT "/usr/users/robert" 250 CWD command successful. or FTP> SET DEFAULT "~robert" To change back to your login default directory, specify a tilde (~) alone, as follows: FTP> SET DEFAULT ~ 250 CWD command successful. FTP> pwd 257 "/usr/users/robert" is current directory. 3 Creating_and_Deleting_Directories To create a directory on a connected remote host, use the CREATE/DIRECTORY command. The following example creates a subdirectory LOCAL_ACCTS in the current working directory on the connected remote OpenVMS host. FTP> CREATE/DIRECTORY [.LOCAL_ACCTS] To delete a directory, use the DELETE/DIRECTORY command as in the following example. The command deletes the directory created in the preceding example. FTP> DELETE/DIRECTORY LOCAL_ACCTS.DIR;* 3 Copying_Files To copy files from a remote host to your local host, use the GET command. To copy files from your local host to a remote host, use the PUT command. To use these commands, you must have an active FTP session with a remote host. You can enter any number of commands during the session. You can also use the COPY/FTP command to copy files across the network using TCP/IP. For more information on this command, type HELP COPY/FTP at the DCL prompt. FTP resolves the differences between UNIX file systems and OpenVMS file systems automatically. By default, the PUT command copies files to UNIX systems using lowercase file names without version numbers. If you use a wildcard to copy all versions of a file and do not specify an output file, the following occurs: o The version numbers become the last element of the copied files. o Semicolons are converted to periods. 4 Store_Unique_Feature The Store Unique (STOU) feature allows you to control how file version numbers are treated when you copy (PUT) files from local to remote hosts. After connecting to the remote host, you toggle the Store Unique feature on and off by issuing the sunique command at the FTP prompt, as follows: FTP> sunique Store unique on. FTP> sunique Store unique off. FTP> sunique Store unique on. The Store Unique feature behaves differently when copying files between OpenVMS and UNIX. It also behaves differently if you use wildcards or specify version numbers. The following table shows the results when you copy the file text.txt from OpenVMS to UNIX. File test.txt Exists Store on UNIX Unique FTP Command System On Store Unique Off FTP> PUT No text.txt text.txt text.txt FTP> PUT Yes text.txt.1 text.txt text.txt The next table shows the results when you copy the file text.txt;* from OpenVMS to UNIX. Files test.txt.1 test.txt.2 Exist on Store UNIX Unique FTP Command System On Store Unique Off FTP> PUT No text.txt.2 text.txt.2 text.txt;* text.txt.1 text.txt.1 FTP> PUT Yes text.txt.2text.txt.2 text.txt;* text.txt.1 text.txt.1.1 4 VMS_Plus_Mode FTP performs fast file transfers between two OpenVMS systems by using VMS Plus Mode. When FTP identifies file transfers between two OpenVMS hosts running TCP/IP Services, it transfers files in large blocks rather than in small records. VMS Plus Mode greatly increases the transfer speed and preserves all Record Management Services (RMS) file attributes. FTP automatically disables VMS Plus Mode when your session is with a UNIX host or with an OpenVMS host not running TCP/IP Services. 4 Preserving_File_Attributes When you transfer OpenVMS files to a UNIX system and back again, some record attributes might be lost. To preserve all RMS file attributes, use the /FDL qualifier (File Definition Language) with the GET and PUT commands. You might also need to use the SET TYPE command to determine the type of file transfer: o Specifying SET TYPE ASCII results in a sequential file with variable records. Select this type when transferring ASCII text files. o Specifying SET TYPE IMAGE results in a sequential file with fixed records of 512 bytes. Select this type when transferring non-ASCII files, such as binary files or executable image files. For example, to transfer an executable image to a remote UNIX host, follow these steps: 1. Specify the IMAGE data type: FTP> SET TYPE IMAGE 2. Transfer the file to the remote host. At the same time, create and transfer a secondary file with the file's OpenVMS record attributes: FTP> PUT/FDL file To retrieve the file from a remote UNIX host, follow these steps: 1. Specify the IMAGE data type: FTP> SET TYPE IMAGE 2. Retrieve the file from the remote host after retrieving and using the secondary file containing the file's OpenVMS record attributes: FTP> GET/FDL file.dat 4 Examples 1. In the following example, the PUT/FDL command does the following: o Creates the FDL file cygnet.bckfdl on the remote host with the RMS attributes of file STAT.BCK. o Transfers the data in STAT.BCK and puts it in to cygnet.bckfdl on the remote host. FTP> PUT/FDL STAT.BCK CYGNET.BCK 200 TYPE set to ASCII 200 PORT command successful 150 Opening data connection for cygnet.bckfdl (130.180.4.8,1028) 226 Transfer complete local: cygnet.bckfdl remote: cygnet.bckfdl 846 bytes sent in 00:00:00.03 seconds 200 TYPE set to IMAGE 200 PORT command successful 150 Opening data connection for cygnet.bck (130.180.4.8,1029) 226 Transfer complete local: STAT.BCK remote: cygnet.bck 8152 bytes sent in 00:00:00.12 seconds In the following example, the GET/FDL command performs the following actions: o Transfers the FDL file cygnet.bckfdl from the remote host to the local host. o Uses this file to re-create the file STAT.BCK, with all of its original RMS attributes, on the local host. o Transfers the data in cygnet.bck to the new local file STAT.BCK. FTP> GET/FDL CYGNET.BCK STAT.BCK 200 TYPE set to ASCII 200 PORT command successful 150 Opening data connection for cygnet.bckfdl (130.180.4.8,1028) 226 Transfer complete local: cygnet.bckfdl remote: cygnet.bckfdl 846 bytes sent in 00:00:00.03 seconds 200 TYPE set to IMAGE 200 PORT command successful 150 Opening data connection for cygnet.bck (130.180.4.8,1029) 226 Transfer complete local: STAT.BCK remote: cygnet.bck 8152 bytes sent in 00:00:00.12 seconds 4 Transfer_Mode TCP/IP Services supports only STREAM mode for data transfer. STREAM mode transmits the data as a stream of bytes. 4 File_Structure TCP/IP Services supports transfers of ASCII (stream, records with variable length) and IMAGE (binary, records fixed at 512 bytes) files. 3 Renaming_and_Deleting_Files To change the name of a remote file, use the FTP command RENAME. The following command renames file YEAR.DAT to YEAR96.DAT on the connected remote host: FTP> RENAME YEAR.DAT YEAR96.DAT To remove a remote file, use the FTP command DELETE. The following command deletes all versions of file YEAR.DAT on the connected remote VMS host: FTP> DELETE YEAR.DAT;* 3 Viewing_File_Contents To display the contents of a file on a connected remote host, use the FTP command VIEW and specify the file name. If the file is not in your current working directory, include the directory name in the file specification. The following example shows how to display the contents of file ENG.DIS located in the remote working directory: FTP> VIEW/PAGE ENG.DIS usrm::"khuna@jnet.com" pobox::bearse yield::timms usrm::"lerry@muster.cudenver.edu" sam nm%us1rmc::"ldutton@TopCom.com" . . . 3 Appending_Files The FTP command APPEND allows you to concatenate a local file to a file on a connected remote host. The following command appends local file JUL_DEC.DAT to file YEAR.DAT on the connected remote host KALI. FTP> APPEND JUL_DEC.DAT YEAR.DAT 200 PORT command successful 150 Opening data connection for year.dat. (130.180.4.8,1108) 226 Append transfer complete local:large.txt remote:remote.dat 15596 bytes sent in 00:00:00.10 seconds (152.30 Kbytes/s) 3 Customizing_FTP You can modify the way FTP transfers files, depending on the following criteria: o The operating system of the remote host o The applications you use o Whether you want wildcard name expansion o The information you want displayed during processing The following are a few of the FTP commands that control FTP command processing: o ENABLE/DISABLE LOG Enables or disables the display of FTP commands sent to the remote host. o ENABLE/DISABLE PARSE Enables or disables the expansion of file name specifications. o ENABLE/DISABLE REPLY Enables or disables the display of all responses from the remote host. o QUOTE Sends FTP commands directly to the remote host without local interpretation. The preceding commands control the way FTP displays command processing information and status. The SHOW STATUS command displays the current status of the FTP client (your local host) and, if you have a connection, of the remote host. By default, FTP returns multiple lines of error messages (MULTILINE is enabled). The first line explains the general problem, while subsequent lines provide details to help you diagnose the source of the problem. These lines may include operating system as well as FTP messages. Applications that use FTP to transfer files under program control often do not need the extra messages returned. To disable the MULTILINE feature, when you supply a password to connect to a remote host, precede the password with a hyphen (-password), as in the following example: $ FTP /USER=SALINGER /PASSWORD=-LETMEIN HAGELS Use the FTP command SHOW STATUS to determine whether the MULTILINE feature is enabled. You can modify the way FTP reacts to errors by using the SET ERROR_LEVEL command. By default, the error level setting is SUCCESS, which means that when FTP is running in batch mode, a warning or error message will cause FTP to exit. (FTP runs in batch mode when FTP commands are executed by a command procedure rather than interactively.) If you do not want FTP to exit upon a warning or error message, you can set the error level to ERROR. For example, in the following command, if the default error level (SUCCESS) is in effect and directory [MILLER.USERS] does not exist, the resulting error would cause FTP to exit. $ FTP CONNECT HAGELS cd [MILLER.USERS] DEL *.*;* EXIT $ If the error level had been set to ERROR, FTP would not exit, and the DELETE command in the command procedure would delete all files in your current working directory. Note that you can also set the error level to WARNING, which causes FTP to tolerate warning messages (but not error messages). 3 Command_Procedures You can use either OpenVMS or UNIX command syntax in DCL command procedures that use FTP. You can use command procedures to invoke FTP tasks, connecting to a remote host and performing assorted file operations with the remote host and you can use command procedures to customize the FTP environment. 4 Initialization_Command_Files Initialization command files can customize your FTP sessions with the SET, ENABLE, and DISABLE commands. These command files are optional. They eliminate the need to enter individual FTP commands, and they run automatically when you invoke FTP. Initialization command files have the following characteristics: o Contain only OpenVMS commands. o Contain only one command per line. o Are generally named SYS$LOGIN:FTPINIT.INI. 4 Examples The following example shows an FTP initialization command procedure. ! This file, FTPINIT.INI, sets my FTP parameters ! the way I like them. ! ENABLE REPLY ENABLE TRANSFER_VERIFICATION SET DEFAULT/LOCAL [MILLER.WORK] When you invoke FTP, the initialization file generates output such as the following, which displays environment status: $ FTP Reply on. Verbose mode on. Bell off. Hash mark printing on (1024/hash mark). Local directory now SYS$LOGIN_DEVICE:[MILLER.WORK] 4 Setting_Error_Level To change the error level, enter the following command, where x is SUCCESS, WARNING, or ERROR: FTP> SET ERROR_LEVEL x o If x is SUCCESS, then WARNING, ERROR, and FATAL cause FTP to exit. o If x is WARNING, then ERROR and FATAL cause FTP to exit. o If x is ERROR, then only FATAL causes FTP to exit. Fatal errors always cause FTP to exit. 3 DECnet_Operations To copy files to and from a DECnet node, use the standard GET and PUT commands You can copy files to and from DECnet nodes and get remote directory information, if your host and the DECnet node are connected through a host running TCP/IP Services for OpenVMS. Use the full file specification, including the node, device, directory, and file name. 4 Examples 1. The following PUT command copies local file FAX.TXT to DECnet node CURTAIL and renames the file to CURRENT.TXT: FTP> PUT FAX.TXT CURTAIL::DISK$3:[GEARY.KEEPS]CURRENT.TXT 2. The following GET command copies remote OpenVMS file HOUSING.TXT from DECnet node HABTAT and renames the file to HOUSE.TXT: FTP> GET HABTAT::DISK$2:[NATL.UTAH.SWEST]HOUSING.TXT HOUSE.TXT 2 SMTP For exchanging electronic mail (e-mail) with users working on internet hosts, the TCP/IP Services product includes Simple Mail Transfer Protocol (SMTP), Post Office Protocol (POP) software, and Internet Message Access Protocol (IMAP). SMTP allows you to use the OpenVMS mail services to send and receive messages exchanged with users on other hosts. The POP and IMAP software allow you to use your PC mail software to receive and send messages. The software stores mail sent to you, even when the PC is turned off. To use TCP/IP mail services, you need the following: o Knowledge of the OpenVMS Mail utility o User names and host names or IP addresses of the people to whom you want to send mail 3 Sending_Mail To send mail to another internet host also running SMTP, simply invoke the OpenVMS Mail utility at the DCL prompt, type SEND at the MAIL> prompt, and enter the destination. A remote destination consists of the destination user name followed by an at sign (@) and the destination host (such as user_name@host). If the user is on your local host, omit the at sign and host name. Specify the destination host as either a host name or an IP address. The OpenVMS Mail utility automatically detects destination addresses that include fully qualified host names (one in which the node component includes a period [.], such as MALCOLM@PHILOS.BU.EDU) and sends the mail using the SMTP protocol, unless your system has been set up to use a different Internet protocol (by defining an alternate protocol with the MAIL$INTERNET_TRANSPORT logical name). However, if you use a destination address that is not fully qualified - that is, one in which the node component does not include a period (.) - the Mail utility by default assumes the address is a DECnet address. For example, if you specified MALCOLM@PHILOS as the destination address, the Mail utility converts it to DECnet format (PHILOS::MALCOLM). You can force the OpenVMS Mail utility to use a specific protocol by defining the MAIL$INTERNET_MODE logical name. This is useful in cases where a mail address, such as MALCOLM@PHILOS, can be valid for either SMTP or DECnet. You can assign one of the following values to the MAIL$INTERNET_ MODE logical name: o SMTP OpenVMS Mail always interprets the node component of an unqualified address as an Internet address specification. (SMTP is the default mode unless you define an alternate Internet transport with the MAIL$INTERNET_TRANSPORT logical name.) o DECNET OpenVMS Mail always interprets the node component of an unqualified address as a DECnet node specification. o HYBRID (the default) OpenVMS Mail uses an Internet protocol if the node component of the address contains a period. If no periods are in the node component, Mail uses the DECnet protocol. Define the logical name in your LOGIN.COM file. For example, the following definition causes the Mail utility to interpret any address that does not include a period in the node component of the specification as an Internet address: $ DEFINE MAIL$INTERNET_MODE SMTP Another way to force the OpenVMS Mail utility to use SMTP is to include the SMTP% prefix immediately before the destination or IP address. Enclose the destination in quotation marks, as in the following example: $ MAIL MAIL> SEND To: SMTP%"malcolm@philos" To prevent the OpenVMS Mail utility from automatically converting an unqualified Internet host name address to a DECnet format, you can do one of the following: o Fully qualify the host name (for example, specify the destination address as MALCOLM@PHILOS.BU.EDU instead of MALCOLM@PHILOS). o Define the MAIL$INTERNET_MODE logical name as SMTP. o Include the SMTP% prefix before the destination address. For more information about the OpenVMS Mail utility and how it interprets addresses, see the appropriate OpenVMS documentation. 3 Outbound_Alias SMTP allows you to specify an outbound alias that is applied to mail as it is sent and also specifies the network address to which a reply is sent. 3 Defining_the_Outbound_Alias To specify an outbound alias, define the TCPIP$SMTP_FROM logical to the text you want your From: header to be. For example, you might define the logical as follows: $ DEFINE TCPIP$SMTP_FROM "bill.smith@xxx.com" This command sets the outbound alias to the following: From: bill.smith@xxx.com Define the TCPIP$SMTP_FROM logical before invoking OpenVMS Mail. If you always want the header to be sent with the outbound alias, define the logical in your login command procedure (LOGIN.COM). The outbound alias must be a valid address to which recipients can reply. If it is not valid, recipients cannot reply to you, and bounced mail messages are not returned to you. If you do not define the TCPIP$SMTP_FROM logical, the From: address on your mail messages is the same one that you have always had. Use only simple 7-bit ASCII characters in the value you assign to the TCPIP$SMTP_FROM logical. Do not use control characters. The address you use to define TCPIP$SMTP_FROM must be an RFC 822 legal SMTP address; that is, user@domain. If the address is not interpreted correctly, the SMTP mailer ignores it and uses the From: address that it has constructed for you. 3 Personal_Name_String If you have defined an OpenVMS Mail personal name, the SMTP mailer appends that string to the outbound alias. For example, a personal name might look like the following: Bill L. Smith Phone: 123-456-8000 The TCPIP$SMTP_FROM logical is defined as follows: $ DEFINE TCPIP$SMTP_FROM "bill.smith@xxx.com" The following example shows the resulting From: header: From: bill.smith@xxx.com (Bill L. Smith Phone: 123-456-8000) The personal name is appended to the From: address only if both of the following conditions are met: o The value you give for the TCPIP$SMTP_FROM logical does not contain parenthetical phrases (text within parentheses). o The From: address contains the SMTP domain string (the @domain portion of the address). To use a different personal name than the one defined in your OpenVMS Mail personal name, define the personal name string as part of the TCPIP$SMTP_FROM logical in a parenthetical phrase after the user@domain address. Separate the address from the parenthetical phrase with a space. Do not use double quotation marks (" ") in the personal name. For example, you can define the outbound alias logical as follows: $ DEFINE TCPIP$SMTP_FROM - _$ "bill.smith@xxx.com (Phone: 123-456-8000 FAX: 123-456-9000)" Note the following restrictions: o The SMTP mailer does not allow you to define the TCPIP$SMTP_ FROM logical using the following syntax: "personal-name" o Do not specify the logical as follows: $ DEFINE TCPIP$SMTP_FROM """personal-name"" " Instead, define the logical as follows: $ DEFINE TCPIP$SMTP_FROM "bill.smith@xxx.com (personal-name)" 3 Substitute_Domain_String If you define TCPIP$SMTP_FROM without an SMTP domain string (the @domain portion of the address), SMTP appends the substitute domain name to the text you define. If you do not define a substitute domain name, the host name is used. For example, the host is configured with a substitute domain name of x.com, and the TCPIP$SMTP_FROM logical is defined as follows: $ DEFINE TCPIP$SMTP_FROM "bill.smith" In this case, the resulting address is as follows: From: bill.smith@x.com However, if the host is not configured with a substitute domain and the host name is host.x.com, SMTP_FROM is defined as follows: $ DEFINE TCPIP$SMTP_FROM "bill smith" In this case, the resulting address is as follows: From: bill.smith@host.x.com 3 Disabling_Modifications To disable the modifications that TCPIP SMTP makes to the value you assign to TCPIP$SMTP_FROM (such as appending the OpenVMS personal name and @domain to a value with no @domain), include the string [VERBATIM]. For example: $ DEFINE TCPIP$SMTP_FROM "[VERBATIM] bill.smith@xxx.com" The resulting address is as follows: From: bill.smith@xxx.com 3 Return-Path_Header The address you define is used for the Return-Path: mail header. The Return-Path: header is used to bounce undeliverable mail. Note that the version of the text used for the Return-Path: header is stripped of comments (such as the personal name string) and always has a domain string. 3 From:_Header When the TCPIP$SMTP_FROM logical is used to set the From: header, the text that would normally have been used for the From: header is added to the headers as an X-VMS-True-From: header. 3 Disabling_Outbound_Alias To disable outbound alias processing and use of the TCPIP$SMTP_ FROM logical, define the following system logical: $ DEFINE/SYSTEM TCPIP$SMTP_PROHIBIT_USER_HEADERS 1 3 Multiple_Recipients To send mail to more than one user, use the SEND command, but at the To: prompt, type a list of names or the name of an existing distribution list. When you type a list of names, use the following guidelines: o Separate the names with a comma ( , ). o If multiple users are on the same remote host, type the full user_name@host combination for each user. o If a user is on your local host, omit the at sign (@) and host name. For example: MAIL> SEND To: user1,user2,user3@host3,user4@host4 In the preceding example, user1 and user2 are located on the local OpenVMS system; user3 is located on host3; and user4 is located on host4. MAIL> SEND To: user1@host5,user2@host5 In the preceding example, both user1 and user2 are located on remote host host5. To send mail to multiple users by entering the name of a distribution list, follow these guidelines: o The file with the distribution list can be yours or belong to someone else. o The file can reside locally or remotely. o Do not include the names of other distribution lists in the distribution list. You can use two kinds of distribution lists: OpenVMS distribution lists and SMTP distribution lists. 4 OpenVMS_list Generate an OpenVMS distribution list as follows: - Create a .DIS file in your own directory or use an existing one. - You can include comment lines (lines preceded by an exclamation mark [!]) in the .DIS list file. - You can include both OpenVMS addresses and SMTP addresses. If you want the OpenVMS Mail utility to use SMTP for all SMTP addresses, qualified and unqualified, either set the MAIL$INTERNET_MODE logical name to SMTP, specify fully qualified SMTP addresses only, or use the SMTP% prefix with the destination enclosed in quotation marks. - To send mail to the people on your distribution list, enter the following command: MAIL> SEND To: @list_name 4 SMTP_list Generate an SMTP distribution list as follows: - Use an existing .DIS file or create a .DIS file in SYS$SPECIFIC:[TCPIP$SMTP] or, if defined on your system, TCPIP$SMTP_COMMON:. - Give the list a unique name that is not the same as a local user name. - To specify comment lines, use an exclamation mark (!) in the first column. - Include only SMTP addresses. - Use one address per line. - To send mail to the people on this distribution list, enter the following command: MAIL> SEND To: list_name@host_where_list_resides If the MAIL$INTERNET_MODE logical name is not set to SMTP, either specify a fully qualified host name or use the SMTP% prefix. 4 Examples The following examples show different methods of using distribution lists. 1. This example sends mail to users whose names are on the local OpenVMS distribution list AGENCIES.DIS. The distribution list file is displayed in this example. The MAIL$INTERNET_MODE logical name is not set, so by default unqualified Internet addresses would be sent over DECnet; therefore, the AUDUBON@NY address is included with the SMTP% prefix and quotation marks. $ TYPE AGENCIES.DIS ! ! This is an OpenVMS distribution file named AGENCIES.DIS. ! SMTP%"audubon@ny" WILLIAMS@BELTWAY.ORG WILDLIFE@DALLAS.ORG jmuir@19.8.7.6 SEC@GP.INTER8.ORG BATES::SCOPE ! $ MAIL MAIL> SEND To: @AGENCIES.DIS Subj: NEWS TO WATCH FOR 2. This example sends mail to users whose names are on the local SMTP distribution list SYS$SPECIFIC:[TCPIP$SMTP]NATL_ INTEREST.DIS. The distribution list file is displayed in this example. $ TYPE NATL_INTEREST.DIS green@19.8.7.6 wlf@19.7.6.5 arlo@19.4.3.2 free::monicaL wendell@biolo.ne.edu $ MAIL MAIL> SEND To: natl_interest@main_office.org Subj: News Items 3. This example sends mail to the users on SMTP distribution list FINANCE_CENTERS.DIS, which is maintained on remote mail server host HOLBROOK. $ TYPE FINANCE_CENTERS.DIS ny_accts@23.9.7.4 sf_stocks@23.7.11.2 dallas_pfs@23.1.5.1 denver_accts@holbrook $ MAIL MAIL> SEND To: finance_centers@holbrook Subj: Portfolio Activity 3 Reading_Mail To read received mail, follow these steps: 1. At the DCL prompt, type MAIL. 2. At the MAIL> prompt, enter the DIRECTORY command to view a list of received messages. 3. Enter the READ command or indicate the message number you want to view in exactly the same way as you would for OpenVMS mail. In the following example, a user views the directory of unread new mail and selects message 3 to read. $ MAIL You have 3 new messages. MAIL> DIRECTORY NEWMAIL # From Date Subject 1 GWAY::SMTP%"helenm@bhc 10-MAR-2001 Just Checking In 2 GWAY::SMTP%"mays@sfg 11-MAR-2001 Common Bases 3 CBIRD::SMTP%"seaway 12-MAR-2001 Cruises MAIL> 3 3 Name_String You can define a personal name string that is included at the top of the mail messages you send. To create a personal name with SMTP mail, use the SET PERSONAL_NAME command. Note the following restrictions: o Enclose the string in double quotation marks. o Do not use additional double quotation marks within the string. o You can use single quotation marks ( ' ' ) within the personal name. o Do not use 8-bit ASCII characters (for example, ä or ö). The eighth bit is truncated. For example, ä becomes d and ö becomes v. The following commmand sets a personal name that includes quotation marks: $ MAIL MAIL> SET PERSONAL_NAME "'Wealth' is in the mind" 3 Carbon-Copies You can enable carbon copying by using the SET CC-PROMPT command. Follow these guidelines when you specify destinations for the CC: prompt: o Follow the OpenVMS Mail conventions for copying mail to other people or to yourself. o For entering the correct address, follow the guidelines listed in the Sending Mail section. The following example sends mail to user AL and copies to users ROLLINS, BOND, and RICH: MAIL> SEND To: al@airways CC: rollins,bond,rich@flight_central.com Subj: Directions for Night Flight 3 Forwarding_Messages You can forward any mail you receive to any internet host. Follow the OpenVMS Mail conventions for forwarding mail. 3 Routing_Mail_Using_UUCP The UNIX-to-UNIX Copy Program (UUCP) lets a system copy files to and from other systems running UUCP. UUCP is usually used to copy files over a dialup connection. To route mail using UUCP, ask your system manager to define the general gateway in the SMTP configuration. To use SMTP to route mail to a system running UUCP, address the mail as follows: MAIL> SEND To: SMTP%"user_name!uucp_host" The following example sends mail to geoffrey at host haldir: $ MAIL MAIL> SEND To: SMTP%"geoffrey!haldir.of.com" Ask your system manager whether you need to specify a gateway host in mail addresses when you work on UUCP dialup lines. 3 Management_Commands The following table lists the management commands that can help you work with SMTP mail currently in a queue. Type them at the TCPIP> prompt. Table 1 Commands for Using SMTP Command Function SHOW MAIL Displays information about mail messages queued to your process' user name. REMOVE MAIL Deletes mail messages that are in a holding state in SMTP queues. SEND MAIL Releases for delivery a mail message that is in a holding state. 3 Displaying_Mail_Status Use the SHOW MAIL command to display the following information about SMTP mail: o Message (entry) number of the queued mail o User name of the sender (to display information about other users, you need SYSPRV or BYPASS privilege) o File name of the queued mail o Status of a message 3 Deleting_Queued_Mail The following examples show how to delete mail messages from SMTP queues using the TCP/IP command REMOVE (similar to the DCL command DELETE/ENTRY). NOTE Use this command only to release mail messages that are being held; do not use this command to delete mail messages in the processing state. 3 Releasing_Queued_Mail The following example shows how to requeue an SMTP mail message that is currently holding, using the TCP/IP command SEND MAIL (similar to the DCL command ENTRY/RELEASE). You are prompted to confirm that you want the mail message requeued. $ TCPIP SEND MAIL /ENTRY=828 _PLUTO$DKD0:[MARLOW]970207015114580_MARLOW.TCPIP_PLUTO;1? y 2 POP With SMTP and the Post Office Protocol (POP) functionality, you can receive and send OpenVMS mail on your PC. POP is a mail repository that accepts and stores your mail even when the PC is turned off. At your request, the POP server reads mail from your OpenVMS NEWMAIL folder, then moves the mail to your MAIL folder. To send and receive mail on your PC, make sure the system manager has configured the POP server for use on your PC (the POP client system). To set up your POP client account, use one of the following methods: o On networks where maximum security is not required, enter your PC mail application and configure a user name and password into the system. The user name and password pair becomes authorization information for the TCP/IP system, not your POP client system. Your PC client sends the password to the POP server unencrypted. As an added security measure, POP permits only two user name and password authorization attempts per TCP connection. o On networks where maximum security is required, enter your PC mail account and configure a user name and shared-secret password into the system. This method is called the APOP authorization method. With this method, you store a shared-secret password in a one-line file named POP_SECRET.DAT in your default OpenVMS mail directory. You can use the DCL command CREATE or your text editor to create the file and specify a password string, then set the file protection to prevent other users from accessing it. For example: $ SET DEFAULT USER$DISK:[JONES.MAIL] $ CREATE POP_SECRET.DAT xyztancreff $ SET FILE/PROT=(s,w,g,o:rwed) POP_SECRET.DAT The shared-secret password cannot exceed 500 characters. Each time you enter your PC mail application, the shared- secret string is sent from the PC client to the POP server using an encryption process. 2 IMAP The IMAP server allows users to access their OpenVMS Mail mailboxes by clients such as Microsoft Outlook so that they can view, move, copy and delete messages. The SMTP server provides the extra functionality of allowing the clients to create and send mail messages. 2 LPR_LPD The Line Printer/Line Printer Daemon (LPR/LPD) supports the DCL commands PRINT, LPQ, and LPRM for remote printing. The LPR/LPD service allows you access to print queues on remote hosts and allows users on remote hosts to access print queues on your system. To use TCP/IP Services network printer services, you need the following: o The name of the remote print queue o Remote Print Server LPD protocol extensions software you need to use the PRINT /PARAMETERS command o TCP/IP Services installed and LPR/LPD enabled on your OpenVMS system 3 Command_Summary To use the remote printing features, enter the commands summarized below. For complete command descriptions, enter HELP and the specific command at the DCL prompt. DCL UNIX Command Command Function PRINT lpr Prints files. LPQ lpq Displays status of a remote print queue. LPRM lprm Removes jobs from a remote print queue. 3 Remote_Print_Queues Your system manager can configure your system with LPR/LPD network services that allow you to use the DCL command PRINT to send print jobs to a print queue on a remote internet host. The remote host can be a UNIX system or another OpenVMS system running LPR/LPD. You print a local file at a printer on a remote host by specifying the remote queue name defined on your local host (see your system manager for queue names). LPD copies the file to the appropriate remote printer's spool directory. A copy of the file to be printed remains in the spooling queue until the printer is ready to print it. When you enter the DCL command PRINT to send a print job to a remote print queue, you use the /QUEUE qualifier to specify the queue name, plus any of the following qualifiers: /AFTER /BACKUP /BEFORE /BY_OWNER /CONFIRM /COPIES /CREATED /DELETE /EXCLUDE /EXPIRED /FORM /HEADER /HOLD /IDENTIFY /JOB_COUNT /MODIFIED /NAME /NOTE /OPERATOR /PARAMETERS /PASSALL /PRIORITY /QUEUE /SETUP /SINCE /USER /WIDTH Two of these qualifiers work differently with TCP/IP Services than they do in an OpenVMS environment without TCP/IP Services. These two qualifiers are: o /FORM o /PARAMETERS NOTE TCP/IP Services does not support layup definition files for print requests to remote print queues. A layup definition file sets up the layup features: borders, sheet margins, alternating margins, pages per sheet, first page, page order, and page grid. 4 /FORM The DCL command PRINT /FORM customizes the look of the printed page. This qualifier associates a form other than the default with the print job. To find out which forms are defined for your system, enter the following command: $ SHOW QUEUE /FORM To find out the currently mounted form or the default form, enter the following command: $ SHOW QUEUE queue /FULL If the form associated with a remote LPD queue specifies a /WIDTH value that is not the standard 132, LPD sends a "W" card in the job's control file with the width specified in the form. 4 /PARAMETERS TCP/IP Services supports numerous options for the DCL command PRINT /PARAMETERS. For example, it supports the PAGE_SIZE option as follows: $ PRINT/PARAMETERS=(PAGE_SIZE=size) /QUEUE=queue_name filename When you enter the PRINT /PARAMETERS=(option=value) command, enclose the following in quotation marks: o Blanks o Nonalphanumeric characters, including spaces and slashes You can use the following /PARAMETERS options for both local printing (standard DCL PRINT) and remote printing (DCL PRINT with LPR/LPD network services). DATA_TYPE NUMBER_UP PAGE_LIMIT PAGE_ORIENTATION PAGE_SIZE SHEET_COUNT SHEET_SIZE SIDES For a full description of the options supported for DCL local and remote printing, enter the following command. $ HELP PRINT_PARAMETER NOTE This help is available only if the DECprint Supervisor (DCPS) software is installed on your system. See your system manager for more information. The following /PARAMETERS options are supported only for use with remote printing. HOST MAIL NOFLAG PRINTER o Use the HOST and PRINTER options together to send a print job to any remote host and printer that do not have a specific print queue defined on the local system. In conjunction with the HOST and PRINTER options, you must also specify the /QUEUE qualifier. The value of /QUEUE should be TCPIP$LPD_OUT. For example, the following command specifies that the file PINS.LIS be sent to printer CT_LN05R on remote host BALT: $ PRINT/PARAMETERS=(HOST=BALT, PRINTER=CT_LN05R) /QUEUE=TCPIP$LPD_OUT PINS.LIS The HOST and PRINTER options allow you to use any available network printers without your system manager having to set up additional LPD remote queues for each of these printers. Specify the remote host name either by the host name or by its fully qualified domain name (such as PACE.STATS.RINGS_ CORP.COM). o The MAIL option causes the remote host to notify you through SMTP mail when the print job completes. The following command specifies the MAIL option: $ PRINT/PARAMETERS=MAIL /QUEUE=DPR_ANSI PINS.LIS o The NOFLAG option suppresses printing of a banner (flag) page at an LPD queue. The following command specifies the NOFLAG option: $ PRINT/PARAMETERS=NOFLAG /QUEUE=DPR_ANSI PINS.LIS 4 Examples The following examples show how to use the remote queue printing capabilities of TCP/IP Services. 1. This example sends local file PINS.LIS to the remote print queue defined locally as FAC3_ANSI and requests notification through SMTP when the job completes at the remote printer. $ PRINT /PARAMETERS=MAIL /QUEUE=FAC3_ANSI PINS.LIS 2. This example shows how to send a local file to the remote print queue defined locally as OUR_PS for printing at a remote printer. The command specifies that text be printed on both sides of each sheet. The file name is ROUGH.TXT. $ PRINT /QUEUE=OUR_PS /PARAMETER=(SIDES=2) ROUGH.TXT 3. This command sends a print job to the remote queue defined locally as YOUR_PS. $ PRINT /QUEUE=YOUR_PS LET.LIS - _$ /PARAMETERS=(DATA_TYPE=POST,PAGE_ORIENTATION=LANDSCAPE,SIDE=2) 4. This example sends a print job to Internet host PACE.SATRN.COM to print on printer K1_PRINTER. $ PRINT /QUEUE=LPD_OUTQ USER$4:[GRANT.FINAN.SALES]ANNUAL.TXT - _$ /PARAMETERS=(HOST=PACE.SATRN.COM,PRINTER=K1_PRINTER) 3 Remote_Queue_Status To display the status of jobs you send to a remote printer, use the LPQ command. The following information is displayed: o Your name o Current rank of job in the queue o Names of the files in job o Job identifier o Total size of job in bytes 4 Examples The following examples show how you can use the LPQ command. 1. This command displays all entries in the LPS40_QUE queue. $ LPQ LPS40_QUE 2. This command displays information about job 4 in the print queue named OFFICE_QUE. $ LPQ OFFICE_QUE /ENTRY=4 3. This command displays information about jobs 1, 2, and 3 in print queue PEACE_Q. $ LPQ PEACE_Q /ENTRY=(1,2,3) 4. This command displays information about user NELSON's jobs in the print queue FRONT_Q. $ LPQ FRONT_Q /USER=NELSON 3 Removing_Print_Jobs To remove your jobs from a remote print queue, use the LPRM command. The LPRM command lets you remove the following: o All of your active jobs o All jobs, if you have the required privileges o Selected jobs 4 Examples The following examples show how you can use the LPRM command. 1. This command deletes job 7 from print queue BASE_Q. $ LPRM BASE_Q /ENTRY=7 2. This command deletes jobs 555, 556, and 558 from queue BASE_Q. $ LPRM BASE_Q /ENTRY=(555,556,558) 3. In this example, the system manager, who has the required privileges, deletes all jobs from queue MAIN_QUE. $ LPRM /ALL MAIN_QUE 3 Remote_UNIX_Files Your system manager can set up a local print queue to handle print jobs for files sent from a remote UNIX host. To print UNIX files on an OpenVMS printer, the UNIX user enters the lpr command. (For more information, see the appropriate UNIX documentation.) Local queues that are set up to receive UNIX print jobs support layup definition files. These are files are supported only on OpenVMS and are used to set the following layup features: borders, sheet margins, alternating sheet margins, pages per sheet, first page, page order, and page grid. 4 Examples The following example sends UNIX file /usr/stanton/recent.cnts to OpenVMS print queue REMOTE_QUEUE4 and specifies the formatting defined in the layup file called layup3. The REMOTE_QUEUE4 print queue is set up as a remote queue in the printcap file by the system manager. % lpr -Llayup3 -Premote_queue4 /usr/stanton/recent.cnts 2 Remote_Commands The Remote (R) commands provided by TCP/IP Services allow you to work in user accounts on remote systems that support the Remote (R) protocols. You can also use commands, shell scripts, and command procedures on these remote host systems without logging in to the hosts. The R commands include o RCP (Remote Copy) o RLOGIN (Remote Login) o RSH (Remote Shell) o REXEC (Remote Execute, invoked by RSH). You enter these commands at your system command-line prompt. To use Secure Shell (SSH) authentication and encryption for remote login, remote command execution, and copying files, refer to the HP TCP/IP Services for OpenVMS Guide to SSH. To use the Remote (R) commands, you need access to a user account on the remote host. Access is granted by either of the following: o An entry in the remote host's authentication or proxy files o Knowledge of a valid remote account and its password 3 User_Guidelines To use a remote command on your OpenVMS system, remote hosts need to know the user name that you want to use on the host. You can provide the user name in either of two ways: o Automatically: You do not need to take any action if your user name is the same on the remote host as it is on the local host. The remote commands automatically supply your local user name as the requested user name on the remote system. o Using the /USER_NAME qualifier: Specify the user name with the /USER_NAME qualifier if your user name is: - Different on the remote host - In mixed case (only for remote hosts that support case- sensitive user names) - The same on the remote host but you want to access the remote host using another user name By default, the R commands send all user names in lowercase letters. If you access a host that supports case-sensitive user names, and the user name you specify has uppercase letters, you can use the /NOLOWERCASE qualifier to maintain these letters as uppercase, or you can specify the /USER_NAME qualifier and enclose the user name within quotation marks. The remote host must also know your password or know you as a trusted user on your local system through a proxy or by authentication. o Accessing remote hosts by providing your password: - Certain systems have case-sensitive passwords. To send your lowercase or mixed-case password to these hosts, enclose it within quotation marks ( " " ). On systems that are not case sensitive, you do not need to enclose your password within quotation marks. - You can specify the password on the command line, as follows: $ RSH WOODS /PASSWORD="Downy" LS You can specify the password when the remote system prompts, as follows: $ RSH WOODS /PASSWORD DIR REXEC password: (password not echoed) o Accessing remote hosts as a trusted user: Most systems use authentication files or proxy accounts that allow trusted users on trusted hosts to access the system by specifying only the user name they want to use. To access a host without specifying the corresponding password, your originating host and user name must have an entry in these authentication files. The authentication file entries contain your originating user name. The R commands convert your originating user name to lowercase unless you use the /NOLOWERCASE qualifier. You may have to contact the system manager of the remote system to determine whether the system is case sensitive and, if so, what case is used in the authentication files. NOTES o To use the REXEC feature, you must always use the /PASSWORD qualifier. o The RLOGIN command does not recognize the /PASSWORD qualifier. If you are a trusted user, you are automatically logged in to the remote system. o If you are not a trusted user, the remote host (REXEC) prompts you to enter a user name and password on the remote system. 3 Command_Syntax o Quotation Marks Use quotation marks (" ") for UNIX host path names that include slashes (/), such as user/simms/offers, and for user/host specifications that include the username@hostname syntax. If the remote host uses case-sensitive user names and passwords, use quotation marks in the following situations: o User names and passwords are mixed case. o Passwords are lowercase. o User names are uppercase, unless you use the /NOLOWERCASE qualifier. o Qualifiers You can specify R command qualifiers in either of two ways: o Enter the qualifiers on the command line, as follows: $ RCP /LOG TRANQUIL:VULTURES [] $ RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE HERON CAT -N STREAMS o Add the same information to your LOGIN.COM file, as shown in the following example: $ ! To customize my R commands: $ ! $ RCP :== RCP /LOG $ RLOGIN :== RLOGIN /EIGHTBIT/ESCAPE_CHAR="+" /TRUNCATE_USER_NAME $ RSH :== RSH /EIGHTBIT /ESCAPE_CHAR="+" /TRUNCATE_USER_NAME $ ! 3 RCP The RCP (Remote Copy) command copies a file between your local host and a remote internet host. You can also use RCP to copy a file between two remote internet hosts. You specify the source and destination file names, each in the format appropriate for the source or destination system. For copying files from one remote host to another, the following rules apply: o If you do not have proxy login accounts (or authentication file entries) for both the source and remote hosts, you must have the same user name and password on both source and destination hosts. Use the /PASSWORD qualifier and, if necessary, the /USER_NAME qualifier, to specify the authentication information for the remote hosts. o If you have a proxy login account (or authentication file entry) on one of the remote hosts only, use the /PASSWORD qualifier and, if necessary, the /USER_NAME qualifier to specify the authentication information for the other host. To recursively copy every file and subdirectory in a directory, use the /RECURSIVE qualifier with the RCP command. To preserve file format and other attributes when copying files between two OpenVMS systems, use the /VMS qualifier (UNIX format: -v option). For more information, see File_Formats. You can also use the COPY/RCP command to copy files across the network. For more information on this command, enter HELP COPY/RCP at the DCL prompt. Note that you can also use FTP to transfer files. 4 File_Formats RCP on OpenVMS is best used for transferring text files. By default, RCP converts any type of OpenVMS file that is not STREAM_LF, FIXED, or UNDEFINED to STREAM_LF format, using the standard OpenVMS CONVERT utility. RCP specifies the files in the following way: FILE;ORGA SEQU;RECO;CARR CARR;FORM STREAM_LF;SIZE 0;BLOCK YES Options available for changing the default behavior for file copy operations include the following: o Convert FIXED and UNDEFINED format files to STREAM_LF You can change the behavior of RCP to convert FIXED and UNDEFINED format files to STREAM_LF format by using the following logical name: TCPIP$RCP_SEND_FIX_FORMAT_AS_ASCII If this logical name is set to the value 1, RCP converts FIXED and UNDEFINED files to STREAM_LF format. If this logical name is set to a value other than 1, RCP will not convert those files that have a fixed-length record size that matches the value of the logical name; RCP will convert all other FIXED and UNDEFINED files. For example, if you set this logical name to 512, RCP will not convert FIXED or UNDEFINED files with a fixed-length record size of 512 (such as OpenVMS executable image files); RCP will convert all other FIXED and UNDEFINED files. o Preserve File Attributes in OpenVMS-to-OpenVMS File Transfer In an OpenVMS-to-OpenVMS transfer, the receiving peer creates the file as a STREAM_LF file by default. You can preserve the file type and other attributes of a file transferred between two OpenVMS systems by using the /VMS qualifier (UNIX format: use the -v option) with the RCP command. WARNING Specify this qualifier only for file copy operations between two OpenVMS systems; otherwise, the operation will fail. 4 File_Size When transferring files, the RCP protocol requires that the length of the file be sent as part of the protocol. The length is interpreted as a signed 32-bit integer. Therefore, files transferred using RCP must be less than 4 GB minus 1 byte. 4 Examples The following examples show how to use RCP commands to copy files from one host to another host: 1. User BEST has the account best on the UNIX host haven. User BEST's password for that account is IMusici, which must be enclosed in quotation marks because it is mixed case. The following command copies the file /symph/nine on haven to the local directory on the OpenVMS system (the UNIX file specification also must be enclosed in quotation marks): $ RCP /PASSWORD="IMusici" "haven:/symph/nine" 2. User BEST has a proxy account on the remote UNIX host musicx. The following command copies the file /symph/pastoral from host musicx to the directory [SYMPH6] on the device DKA300: on BEST's local OpenVMS system: $ RCP "musicx:/symph/pastoral" ":DKA300:[SYMPH6]" 3. With the following command, user BEST copies each subtree rooted at the /symph directory to the directory [SYMPHS] on the device DKA300: on BEST's local OpenVMS system. $ RCP/RECURSIVE "haven:/symph" ":DKA300:[SYMPHS]" 4. With the following command, user BEST copies all files from the directory /symphonies on remote host musicx to the directory /symph on remote host haven: $ RCP /PASSWORD="IMusici" "musicx:/symphonies/*" "haven:/symph/*" 5. In the following example, user BEST uses the DCL command COPY/RCP to transfer the complete subdirectory tree /symph from remote UNIX host haven to remote OpenVMS host FRAM. Both hosts require a password. (When using the RCP command to transfer files between two remote hosts, you need a proxy account or an entry in the authentication file for at least one of the two remote hosts.) User BEST has an account under the same name on both hosts. $ COPY/RCP haven"BEST IMusici"::"/symph/*" To: FRAM"VAUGHN MYLES"::[classic.compositions]*" 3 RLOGIN The RLOGIN (Remote Login) command connects your terminal to the remote host you specify and requests a login. If the remote host has an entry in its authentication files for your host and user name, it may bypass its login and password prompts. Note that you can also use TELNET to log in to remote internet hosts. End your remote login session in one of the following ways: o Log out from the remote host. o On a new line, enter the escape character and a period. The default escape character is a tilde ( ~ ). To set another escape character, use the /ESCAPE_CHARACTER qualifier on the RLOGIN command line. 4 Examples The following examples show how to use the RLOGIN command. 1. The following command logs in to node CONDO: $ RLOGIN CONDO CONDO - Unauthorized access is prohibited Username: KING Password: (password not echoed) Welcome to OpenVMS (TM) Alpha Operating System, Version V7.3 on node CONDO Last interactive login on Thursday, 24-SEP-2001 15:20:29.60 Last non-interactive login on Wednesday, 23-SEP-2001 14:25:04.12 $ RUN ... $ ~. (characters not echoed) %RLOGIN-S-LCLCLOSED, Local connection closed $ 2. The following command logs in to host petrel and changes the character used to close the RLOGIN session: $ RLOGIN /ESCAPE_CHARACTER="+" PETREL . . . Last login: Mon Mar 14 18:34:27 from phoebe.edu UNIX System petrel: Fri Mar 19 11:02:20 EST 2002 Mon Jun 28 18:44:42 EST 2002 % ls ... % +. (characters not echoed) %RLOGIN-S-REMCLOSED, Remote connection closed $ 3 RSH The RSH (Remote Shell) command connects your terminal to a remote host and requests it to execute the command, script, or command procedure that you specify. If the command generates output, you see it as if it were produced locally. If you omit a remote command when you enter an RSH command line, RSH initiates an RLOGIN session. However, if the command line includes the /PASSWORD qualifier, the remote login attempt fails. Using the /PASSWORD qualifier invokes REXEC. Syntax rules require that you enter your RSH command line so that the remote command is the last word. Quotation Marks If the remote command is one or more lowercase words, you do not need to enclose them in double quotation marks on the RSH command line. However, double quotation marks ( " " ) are required for the following: o Mixed-case UNIX commands o Uppercase UNIX commands In addition, RSH handles one double quotation mark ( " ) and two consecutive double quotation marks ( " " ) in the following manner: o If you enter one double quotation mark on a command line, RSH removes it. o If you enter two consecutive double quotation marks on the command line, RSH removes the first quotation mark and leaves the second. o If you enclose text within double quotation marks on a command line, RSH disables the default conversion of characters to lowercase and removes the quotation marks. Note that, as a general rule, if you are uncertain about whether or not to use quotation marks, you should use them. Interrupting Commands To stop remote execution of a command, press either Ctrl/C or Ctrl/Y. 4 Examples The following examples show how to use the RSH command. 1. In the first example, the remote system manager previously created an entry in the authentication files for remote user STAN on host oster, giving STAN permission to access user rolly. From the local OpenVMS host, user STAN views rolly's directory, which resides on UNIX system oster. No quotation marks are required around the user name and host name because RSH by default sends them in lowercase. $ RSH /USER_NAME=ROLLY OSTER LS 2. On the following RSH command line, the uppercase UNIX qualifier -R is entered within quotation marks to preserve the uppercase R. This example assumes that the user's originating host and user name are in the authentication files on the remote host debts. $ RSH DEBTS LS "-R" 3. The following commands show how RSH sends quotation marks to a remote UNIX host and how quotation marks affect case. All examples assume that the user's originating host and user name are in the authentication files on the remote host. $ RSH DEBTS ECHO TEST MESSAGE test message $ RSH DEBTS ECHO "\""test\"" message" "test" message RSH DEBTS ECHO "TEST" MESSAGE TEST message $ RSH DEBTS "echo '""test"" message'" "test" message 4. Because a remote command is not specified on the RSH command line, TCP/IP Services executes RLOGIN. $ RSH MOON01 Password: (password not echoed) Last successful login for jjones: Fri Sep 25 10:58:31 2003 from nebula Last unsuccessful login for jjones: Fri Sep 25 11:59:43 2003 on ttyp5 Tru64 UNIX V5.0 (Rev. 148); Tue Apr 7 18:32:54 EST 2003 Compaq Computer Corporation Internal Use Only moon01> 5. In this example, the OpenVMS system manager of host WR2 previously created an entry in the authentication files for remote user SIMMS on host WR1. From OpenVMS host WR1, user SIMMS enters the DIRECTORY command to execute at host WR2. $ RSH WR2 DIRECTORY 6. In this example, the OpenVMS system manager of host WR2 previously created an entry in the authentication files for remote user SIMMS on host WR1, allowing user SIMMS access to the user name ROGERS. User SIMMS enters the DIRECTORY command from host WR1 to execute at host WR2 in user account ROGERS. $ RSH WR2 /USER=ROGERS DIRECTORY 3 REXEC Use the REXEC feature to send a command to execute on a remote host that does not have, or might not have, the authentication information that RSH requires. The remote system's authentication files are not used. Along with the remote command, REXEC sends the password you specify on the command line to the remote host. This password is used for security checking. The Remote Shell program (RSH) invokes REXEC. To use REXEC, enter RSH /PASSWORD. REXEC then functions like the RSH command. 4 Examples The following example shows how to provide password information for the RSH command, thereby invoking the REXEC feature on the remote host. From host GRANT, user STANTON enters the file tops.holdings that resides on UNIX host oster. Because STANTON is not listed in oster's authentication files, user STANTON must use the REXEC feature and supply the /USER_NAME and /PASSWORD qualifiers. Quotation marks are required around the password because it contains uppercase letters. $ RSH OSTER /USER_NAME=STANTON /PASSWORD="KeepingSaneJoy" - _$ CAT TOPS.HOLDINGS 2 TELNET With the TELNET software in TCP/IP Services, you can log in to a remote internet system. This is called establishing a TELNET session. Your terminal appears to be attached directly to the remote system. You can establish a TELNET session with a host that uses IBM 3270 model terminals (TN3270). Note that you can also use RLOGIN to log in to remote internet hosts. However, RLOGIN does not have the ability to manage a 3270 session. To use the network terminal services, you need the following: o A user account on the remote host also running TELNET o A user account on the OpenVMS system that runs TCP/IP Services For more information about specific TELNET commands, enter the following command: $ TELNET TELNET> HELP 3 Command_Summary To use TELNET, enter the commands summarized below. For complete descriptions (including UNIX equivalents) of each command, enter the following command: $ TELNET TELNET> HELP Command Description Starting (at the DCL Prompt) TELNET Invokes TELNET. TELNET remote_host Invokes TELNET and establishes a connection to a remote host. TN3270 Invokes TELNET and TN3270. TN3270 remote_host Invokes TELNET, runs TN3270, and establishes a connection to a remote host. Getting In and Out of Sessions CONNECT Establishes a connection between the local host and a remote host. CREATE_SESSION Establishes a pseudo device and connects it to a remote listener port. DELETE_SESSION Deletes a pseudo device created by the CREATE_SESSION command. DISCONNECT Terminates your current session. Ctrl/] Takes you from the remote host back to the TELNET prompt. EXIT Closes open connections and exits from TELNET. HELP Invokes online help. RESUME Resumes an open connection. SPAWN Suspends your TELNET session and takes you to the DCL prompt. Customizing the TELNET Environment DISABLE AUTOFLUSH Disables the automatic flushing of output when interrupt characters are sent. DISABLE AUTOSYNCH Disables the automatic sending of interrupt characters in urgent mode. DISABLE BINARY Disables transmission in binary mode. DISABLE CRLF Disables the sending of carriage returns as Return LF. DISABLE CRMOD Disables the mapping of received carriage returns. DISABLE DEBUG Disables the display of data flow information in hexadecimal. DISABLE Disables the interpretation of certain LOCAL_CHARS control characters by your local TELNET client and passes them to the remote TELNET server. DISABLE Disables the display of option negotiations OPTIONS_VIEW between the client and server. ENABLE AUTOFLUSH Enables the automatic flushing of output when interrupt characters are sent. ENABLE AUTOSYNCH Enables the automatic sending of interrupt characters in urgent mode. ENABLE BINARY Enables transmission in binary mode. ENABLE CRLF Enables the sending of carriage returns as Return LF. ENABLE CRMOD Enables the mapping of received carriage returns. ENABLE DEBUG Enables the display of data flow information in hexadecimal. ENABLE LOCAL_CHARS Enables the interpretation of certain control characters by your local TELNET client and prohibits them from being passed to the remote TELNET server. ENABLE OPTIONS_VIEW Enables the display of option negotiations between the client and server. SHOW PARAMETERS Displays the current parameter settings. SHOW SESSION Displays the current sessions. SHOW STATUS Displays the current status. SET ECHO Sets the echo character to the specified character. SET ERASE Sets the erase character to the specified character. SET ESCAPE Sets the escape character to the specified character. SET FLUSHOUTPUT Sets the flush output character to the specified character. SET INTERRUPT Sets the interrupt character to the specified character. SET KILL Sets the kill character to the specified character. SET MODE Sets the transmission mode to character or line. SET QUIT Sets the quit character (an alternate interrupt character) to the specified character. SET TERMINAL Sets the terminal type to the specified model. Sending Commands to the Remote Host SEND AO Sends the Abort Output command. SEND AYT Sends the Are You There command, testing the path to the remote application and eliciting connection status information from the remote host. SEND BRK Sends the Break command. SEND EC Sends the Erase Character command. SEND EL Sends the Erase Line command. SEND GA Sends the Go Ahead command. SEND IP Sends the Interrupt character. SEND NOP Sends the No Operation command to test whether data can be sent to the remote host, eliciting an error if the connection is not open. SEND SYNCH Sends the Synchronize character. 3 Command_Syntax Use the following rules when you enter a TELNET command line. o Command formats With the TELNET command and most of the commands entered at the TELNET prompt, you can use either DCL or UNIX syntax. For example, the following two commands produce the same results: $ TELNET TELNET> SHOW PARAMETERS $ TELNET TELNET> DISPLAY o Quotation marks Do not include quotation marks on the command line, as shown in the following examples: o The TELNET command line: $ TELNET CENTRAL o The TN3270 command line: $ TN3270 CENTRAL o Commands at the TELNET prompt: TELNET> CONNECT CENTRAL 4 Example The following example connects to UNIX host migain and sets a terminal type with the /TERMINAL_TYPE qualifier. No quotation marks are needed to pass a terminal type to migain in lowercase, as demonstrated with the remote host's printenv command. $ TELNET MIGAIN /TERMINAL_TYPE=vt300 %TELNET-I-Trying, Trying ...11.90.208.56 %TELNET-I-SESSION, Session 01, host migain, port 23 -TELNET-I-Escape, Escape character is '^]' Hello from UNIX host migain login: root Password:... . . . migain# printenv TERM=vt300 HOME=/ SHELL=/bin/csh USER=root PATH=/bin:/usr/bin:/usr/ucb:/etc:/usr/etc:. LOGNAME=root PWD=/ migain# 3 Starting You can start a TELNET or TN3270 session with a remote host (also called establishing a connection and opening a connection) in one of the following ways: o At the DCL prompt, enter either the TELNET or the TN3270 command and specify a remote host. o At the DCL prompt, enter either the TELNET or the TN3270 command with no parameters. At the TELNET or TN3270 prompt that appears, enter the CONNECT or open command, and specify a remote host. o Invoke and use TELNET or TN3270 from a command procedure. 4 Example The following example shows three ways to establish a connection interactively: $ TELNET CENTRAL /TERMINAL_TYPE=IBM-3278-2 $ TELNET TELNET> CONNECT CENTRAL 23 VT200 $ TN3270 CENTRAL /TERMINAL_TYPE=IBM-3278-3 You can invoke TELNET or TN3270 and, without connecting to a remote host first, enter certain commands that customize the sessions and display parameters or status, as shown in the following example: $ TELNET TELNET> SHOW STATUS %TELNET-E-NOSESSION, No active session Escape character: '^]' TELNET>SET DEVICE TERMINAL=VT300 TELNET> OPEN GALAXY %TELNET-I-TRYING, Trying ... 1.20.208.10 %TELNET-I-SESSION, Session 01, host galaxy, port 23 -TELNET-I-ESCAPE, Escape character is ^] Compaq Tru64 UNIX (galaxy.udb.com) (ttyp5) login: 3 Exiting You can end a TELNET or TN3270 session (close the connection) in one of the following ways: o At the remote host's system prompt, log out. o At the remote host's system prompt, return to the TELNET or TN3270 prompt and disconnect the session, as follows: 1. At the remote host's system prompt, press the TELNET/TN3270 escape character (Ctrl/] is the default). 2. At the TELNET or TN3270 prompt, enter either the DISCONNECT or the close command. 4 Example The following example shows two ways to close connections: % logout %TELNET-S-REMCLOSED, Remote connection closed -TELNET-I-SESSION, Session 01, host galaxy, port 23 TELNET> TELNET> EXIT $ % (characters not echoed) TELNET> DISCONNECT galaxy.udp.com> TELNET> DISCONNECT %TELNET-S-LCLCLOSED, Local connection closed -TELNET-I-SESSION, Session 01, host galaxy, port 23 TELNET> 3 Logging_Sessions To keep a log of your TELNET session, use the /LOG_FILE qualifier. (You cannot use this qualifier with a TN3270 session.) The following example establishes a TELNET connection to node central, sets the terminal type to VT200, and logs all session output to the file CENT.LOG in your current directory. $ TELNET/LOG_FILE=CENT.LOG/TERMINAL_TYPE=VT200 CENTRAL 3 Command_Procedures You can create a command procedure containing the DCL commands DEFINE and TELNET (or TN3270) commands. You can create initialization command files to customize your TELNET/TN3270 sessions with SET, ENABLE, and DISABLE commands. These command files: o Are optional. They eliminate the need to enter individual TELNET commands. o Have the following requirements: - Location: Your login directory - Name: TELNETINIT.INI - Format: one command per line o Run automatically when you invoke TELNET or TN3270. o Let you specify the logical name, TELNETINIT, to point to an initialization file. 4 Example The following example shows a TELNET initialization command procedure: ! This file, TELNETINIT.INI, sets my TELNET parameters ! the way I like them. ! DISABLE AUTOFLUSH ENABLE BINARY ENABLE DEBUG SET DEVICE /TERMINAL=VT300 SET ESCAPE "^p" 3 Toggling During a session with a remote host, you can toggle between the local TELNET or TN3270 process and the connected host. For example, at the TELNET prompt, you might want to display status, modify a TELNET parameter, or spawn a DCL subprocess. o To return to the local TELNET or TN3270 prompt (TELNET command mode), enter the TELNET escape sequence (the default is Ctrl/]) at the remote host's prompt (TELNET input mode). o To resume your session with the remote host, enter one of the following at the TELNET (or TN3270) prompt. TELNET> or TELNET> RESUME or TELNET> RESUME n where n is the number of the session to which you want to return. o To change the default escape sequence, enter the following at the TELNET (or TN3270) prompt: TELNET> SET ESCAPE "^escape_character" 4 Examples 1. The following example toggles between remote UNIX host biway and the local OpenVMS system. biway> (characters not echoed) TELNET> SHOW STATUS Session 1 Active Host biway Port 23 Operating Mode: Character-at-a-time Escape character: '^]' Options: Echo - Remote Terminal Type - Local Terminal Type - VT300 Suppress Go Ahead - Local Suppress Go Ahead - Remote Terminal Dataoveruns: 0 Suspended Network I/Os: 0 . . . TELNET> biway> 2. In the next example, user BENTLEY, working at OpenVMS node EAGLE, uses TELNET to do the following: 1. Establish a connection to UNIX host fern. 2. Return to the local TELNET prompt. 3. Display status. 4. Establish a connection to host gannet. 5. Return to the TELNET prompt. 6. Display status. 7. Connect to sands. But sands closes the connection because BENTLEY incorrectly enters the password three times. 8. Try to resume the session with gannet. However, RESUME without specifying a session number fails: - With multiple sessions, RESUME's default is the "active" session, the one with the most recently opened connection. - The host to which BENTLEY connected most recently is sands. However, because BENTLEY incorrectly typed the password during login, sands closed the TELNET connection and displayed the following: No current session. - Because no connection is active (or current), BENTLEY must specify a session number on the RESUME command line. $ TELNET FERN . . . fern> (characters not echoed) TELNET> SHOW STATUS Session 1 Active Host FERN . . . TELNET> CONNECT GANNET . . . gannet> (characters not echoed) TELNET> SHOW STATUS Session 2 Active Host GANNET Operating Mode: Character-at-a-time Escape character: '^]' . . . Session 1 Waiting Host FERN TELNET> CONNECT SANDS %TELNET-I-Trying, Trying...11.18.222.95 %TELNET-I-SESSION, Session 03, host sands, port 23 -TELNET-I-Escape, Escape character is '^]'. . . . Username: BENTLEY Password: User authorization failure Username: BENTLEY Password: User authorization failure Username: BENTLEY Password: User authorization failure Remote connection closed TELNET> RESUME No current session TELNET> SHOW STATUS Session 1 Waiting Host FERN Session 2 Waiting Host GANNET . . . TELNET> RESUME 2 gannet> (characters not echoed) TELNET> SHOW STATUS Session 2 Active Host GANNET Operating Mode: Character-at-a-time Escape character: '^]' . . . Session 1 Waiting Host FERN TELNET> 3 Suspending While using TELNET, you can use the SPAWN command to suspend your current session and create a subprocess at the local DCL prompt. At the DCL prompt, you can then enter any number of DCL commands. To return to your suspended TELNET session (exiting the DCL subprocess), enter the LOGOUT command. 4 Example In the following example, the user suspends the TELNET session to list the files in the working directory on the local host and deletes one of the files in that directory and then returns to the TELNET session. TELNET> SPAWN $ DIR . . . $ DEL TR3.TXT:* $ LOGOUT Process FERN_1 logged out at 17-JAN-2002 11:08:24.90 TELNET> 3 Multiple_Sessions TELNET supports: o Multiple simultaneous connections o 10 or more simultaneous sessions o Only one session at a time if it uses TN3270 The TELNET command SHOW STATUS helps you keep track of multiple sessions. o Toggling Sessions To toggle between one open TELNET connection and another: 1. Enter the TELNET escape sequence. 2. If necessary, use the SHOW STATUS command to check the number of your session with the other host. 3. Enter the TELNET RESUME n command, where n is the number of the session to which you want to return. o Session Information To display a list of your active sessions, use the following SHOW SESSION command: TELNET> SHOW SESSION Session 01, host finder, port 23 Session 02, host keeper, port 23 (default active session) If there are no active connections, the SHOW SESSION command displays the following message: %TELNET-E-NOSESSION, No active session 3 Customizing To customize the TELNET/TN3270 processing environment, use the ENABLE, DISABLE, and SET commands. You can modify how TELNET and TN3270 perform the following actions: o Send and receive transmissions o Display processing on your terminal o Interpret certain control characters You can redefine the following control characters, in situations when, for example, your terminal or the remote host does not recognize the corresponding default control character. o Echo o Erase o Escape o Flush output o Interrupt o Kill o Quit Use the SET command to redefine these characters. For example, the following command defines the interrupt character to be the letter a or A. TELNET> SET INTERRUPT "^a" TN3270 allows you to redefine your keyboard. You can redefine most IBM 3270 model functions and all emulated functions and characters. You can create a key definition file with DEFINE/KEY statements to redefine the keyboard. Alternatively, you can redefine a key interactively by using the DEF KEY function (Ctrl/K on VT100-and VT200-series terminals) You can determine the mode TELNET uses to transmit data. The appropriate TELNET mode for a session depends on: o The remote host to which you are connecting o The applications you use The following table shows the modes that control TELNET communications. Mode Function Local Characters The local host interprets control characters, Mode translating them to TELNET protocol sequences (ENABLE LOCAL_CHARS). Use this mode when the local and remote hosts implement different control characters. By default, characters are interpreted by the remote host (DISABLE LOCAL_ CHARS). Binary Mode The local host sends transmissions in binary mode (ENABLE BINARY). Use this mode when the remote host expects each line of data to end with a carriage return/line feed combination. By default, the local host sends transmissions with the end-of-line (EOL) character mapped to the carriage return/line feed combination (DISABLE BINARY). Debug Mode TELNET displays data flow in both hexadecimal and readable text (ENABLE DEBUG). By default, TELNET displays data in readable text only (DISABLE DEBUG). Character TELNET transmits data one character at a time Transmission (SET MODE CHAR) rather than line by line. Use Mode this mode when you run a text editor (on the remote host) that does character processing. Character transmission mode is the default. Line TELNET transmits data one line at a time (SET Transmission MODE LINE). Most clients send a character at a Mode time. The remote host server must support line transmission mode. This allows you to do signal trapping as well as local-character editing and tab expansion. 3 TN3270 You can run a TELNET session with a host that uses IBM 3270 model terminals by using the TN3270 command. The TN3270 command: o Provides IBM 3270 Information Display System (IDS) terminal emulation. o Assigns IBM 3270 functions to your keyboard. o Assigns IDS functions to specific keys. During a TN3270 session, you can do the following: o Record your sessions (Recording Sessions). o Redefine keys permanently (Key Definition File). o Redefine keys interactively (DEF KEY Function). o Troubleshoot problems (TN3270 Troubleshooting). NOTE When you run TN3270, you can only have one session. You cannot have other sessions running simultaneously, as you can when running normal TELNET sessions. TELNET can emulate the following IBM 3270 model terminals: Model Screen Size (Rows x Columns) IBM 3278 Model 2 24 x 80 IBM 3278 Model 3 32 x 80 IBM 3278 Model 4 43 x 80 IBM 3278 Model 5 27 x 132 4 Terminal_Setup When you use TELNET and specify IBM 3270 model terminal emulation (TN3270), the image displayed on your screen depends on the type of terminal you use (or that your PC is emulating) and the features you set on it. o VT200 Series Terminals To set up a VT200-Series terminal for emulation, follow these steps: 1. At the Set-up Directory menu, select the keyboard type that corresponds to the keyboard layout you are using (for example, North American). 2. At the Display Set-up menu, select the following: o Interpret controls o Light text, dark screen o Cursor (visible) 3. At the General Set-up menu, select the following: o VT200 or VT100 mode (if VT100 mode, set VT100 ID) o 7-bit or 8-bit controls o Multinational/national o Normal cursor keys o No new line 4. At the Communications Set-up menu, select the following: o XOFF at 64 or XOFF at 128 o 8-bit communication line o 8-bit (any) parity o No local echo 5. At the Keyboard Set-up menu, select warning bell ON. At the DCL prompt, enter the following command: $ SET TERMINAL /INQUIRE The software determines the terminal's characteristics and sets the appropriate parameters. If you select National character mode, enter the following command: $ SET TERMINAL /NOEIGHTBIT o VT100 Series To set up a VT100-Series terminal for emulation, follow these steps: 1. Set your terminal to ANSI mode (see the user's guide for your terminal). 2. Enter the following command at the DCL prompt: $ SET TERMINAL/INQUIRE This command causes the terminal to be questioned about its characteristics. The appropriate parameters for the terminal are set up according to its response. TN3270 requires terminal windows that support at least 24 lines and 80 columns. 4 Starting_and_Exiting Start a TN3270 session by using the TN3270 command. You can also use the TELNET/TERMINAL_TYPE=IBM-3278-n command. The default terminal type is IBM-3278-2. You can invoke TN3270 and, without first connecting to a remote host, enter certain commands that customize the sessions and display parameters or status. You can also use a command file to invoke TN3270 and the customization. The TN3270 command includes several qualifiers that allow you to specify customized or special files for the following: o Character-set translation tables file (/CHARACTER_ SET=file) that translates between EBCDIC and the DMCS. The default file, if set up by your system manager, is SYS$LIBRARY:TN3270DEF.TBL. If this file does not exist, and you do not specify a file, TN3270 uses its own translation table. o Keyboard definition file (/KEY_DEFINITIONS=file) that you create as an alternative to the default keyboard layout. o National Replacement Character Set (NRCS) file (/NATIONAL_ CHARACTERS=n) for which your terminal is configured. The default for 8-bit terminals is MULTINATIONAL. The default for 7-bit terminals is US_ASCII. You can end a TN3270 session (close the connection) in one of the following ways: o At the remote host's system prompt, log out. o At the remote host's system prompt, return to the TN3270 prompt and disconnect the session as follows: 1. At the remote host's system prompt, press the TN3270 escape character (Ctrl/] is the default). 2. At the TN3270 prompt, enter either the DISCONNECT or the close command. Clearing Error Messages TN3270 displays error messages in a bordered display at the bottom of your screen. This display overwrites the status display and remains visible until you clear it. To clear the display, invoke one of the following functions: o REFR o HELP o SET FIL o DEF KEY Recording Sessions During a TN3270 session, you can record your screen's contents. The PRINT function directs your screen's contents to either a file or a spooled printer. To record your screen's contents, follow these steps: 1. Invoke the PRINT keyboard function, as described in the topic Keyboard_Functions. The screen display is recorded in a file in a compressed state. Null lines (lines with only nulls and attribute characters) do not appear. 2. Invoke the ENTER function or any function that transmits the screen contents to the remote host's application, as described in the topic Keyboard_Functions. This creates the default output file, TN3270PRINT.LIS. TELNET does the following: o Each time you start a TELNET session that runs TN3270, TELNET opens a new TN3270PRINT.LIS file. o Each time you use PRINT during a session, TELNET appends new output from the screen to the end of TN3270PRINT.LIS. o Each time you use PRINT, if you direct the output to a printer, TELNET creates a separate entry in the print queue. o If the printer is spooled, TELNET immediately prints the output. You can specify a different file name. To change the name, use one of the following methods: o When you start a TN3270 session, use the /PRINTER qualifier, as shown in the follwing example: $ TN3270 [ host ] /PRINTER=file o During a TN3270 session, follow these steps: 1. Use the SET FIL keyboard function, as explained in the topic Keyboard_Functions. 2. At the prompt for a new file name, enter a name. If you specify the same name that is already in use, subsequent PRINT operations direct output to a new version of the same file. 3. Use the NEW LINE keyboard function, as explained in the topic Keyboard_Functions. Locked Keyboards If your keyboard locks, the terminal bell rings, and the status line displays the following information: Inhib To unlock the keyboard, press the KP0 key to invoke the RESET function. (KP0 refers to the zero (0) key in the application keypad on the right hand side of the keyboard.) Do not use the following functions when the cursor is in a protected field (a field that does not accept user input): o DELETE o DUP o ER EOF o FM o Any graphic character 3 TN3270_Keyboard_Functions The options listed below under "Additional Information Available" describe the keyboard functions. Preceding each function description are the key sequences for VT100 and VT200 terminals and the function name to use in a DEFINE/KEY command. In many of the key sequences, TN3270 allows use of the extended function (EXT) feature. Used in conjunction with another key, EXT allows access to an extended function for that key. The following illustrates the extended function feature in more detail. 4 ATTACH VT100: EXT + E VT200: EXT + Find DEFINE_KEY Function: ATTACH Changes control from one subprocess to another subprocess or to the parent process. When you invoke the ATTACH function, TN3270 uses the name of the last process to which you attached as the default process name. If you want to attach to a different process, press Ctrl/U to erase the default process name. You can then enter the process name of your choice at the prompt. The process name can be a quoted string. Use the quotation marks to preserve spaces, tabs, or lowercase letters in strings. 4 ATTN VT100: EXT + A VT200: F19 DEFINE_KEY Function: ATTENTION Provides a way to "get the attention of" the remote application program that you are running by sending a SIGNAL RU command to the remote host. See the user's guide of the particular application program to learn what response the program gives when you use this key. 4 Back_Tab VT100: BACKSPACE VT200: F12 DEFINE_KEY Function: BACK_TAB Moves the cursor, depending on the type of screen. On a formatted screen, the cursor moves one of the following ways, depending on the cursor's location when you press this key: o If the cursor is in a field, but not at the first position of the field, it moves to the beginning of the unprotected field that it is in. o If the cursor is in the first position of a field, it moves to the beginning of the preceding unprotected field. If the cursor is in the first position of the first unprotected field, the cursor moves to the first position of the last unprotected field on the screen. On an unformatted screen, the cursor returns to the first position on the screen. 4 Cent_Sign VT100: EXT + C VT200: EXT + C DEFINE_KEY Function: (None) Enters a cent sign. If your terminal does not have this character, your screen displays a hyphen ( - ). 4 CLEAR VT100: EXT + Enter VT200: EXT + F20 DEFINE_KEY Function: CLEAR Clears the screen and moves the cursor to the first position on the screen. When you invoke the CLEAR function, the software notifies the application program that this function has been used. 4 DEF_KEY VT100: Ctrl/K VT200: Ctrl/K DEFINE_KEY Function: DEFINE_KEY Lets you interactively define or redefine a key. You get a prompt for the name of the key to define and for a function you want to assign to that key. 4 DELETE VT100: Delete VT200: