UNIX Client-Server Program Interface, UCSPI-1996 Copyright 1996 D. J. Bernstein, djb@pobox.com 1. Introduction This document describes the UNIX Client-Server Program Interface, UCSPI (ooks-pie), a command-line interface to client-server communications tools. UCSPI provides several benefits. First, the UCSPI interface is independent of the underlying communications medium; UCSPI applications don't even have to be recompiled as the Internet upgrades from IPv4 to IPv6. Second, UCSPI lets shell scripts take advantage of networking. Third, UCSPI clients and servers conventionally set up environment variables that display the local and remote addresses, so the information is readily available to applications and users. Here is the general UCSPI framework. An UCSPI tool is a program that understands how to talk to some communications medium. It sets up two descriptors and then invokes an UCSPI application, which can read from one descriptor and write to the other. Every communications medium provides reliable two-way full-duplex strictly ordered not necessarily timed stream communication. Some media may provide other types of communication, such as expedited (``out-of-band'') transmission, in which the stream is no longer ordered, but most UCSPI applications are medium-independent and do not rely on such features. 2. Tools UCSPI tools are executable programs. They accept command lines in the following general format: [tool] [options] [address] [application] Here [tool] is the name of the tool, [options] are zero or more option arguments, [address] is a protocol-specific address, and [application] is a user-specified program to run for each connection. [options] are processed by the getopt standard; thus an argument of -- terminates [options]. [tool] supports three options to control how much information it prints to stderr: -v all available messages -Q all available error messages; no messages in case of success -q no messages in any case The default is -Q; later arguments override earlier arguments. [tool] may support many further options. [application] consists of one or more arguments, handled by the conventions of execvp(). [tool] passes on all [application] arguments without change, no matter what characters appear in those arguments. [tool] always changes certain file descriptors, as described in section 3, and environment variables, as described in section 4, before executing [application]. [tool] might fork before executing [application], and it might reset some signals that were previously ignored. Other than this, [tool] does not change its process state before executing [application]. [tool] does not assume that any particular descriptors are open or closed upon entry. [tool] does not force itself into the background; nor does it attempt to detach from a controlling terminal. If [tool] cannot perform its functions, it exits with a nonzero code. 3. Clients and servers There are two types of UCSPI tools: clients and servers. An UCSPI client closes descriptors 6 and 7 and connects to a server at [address]. Upon connecting, it spawns [application] with descriptor 6 reading from the connection and descriptor 7 writing to the connection. The client does not make any further connections. When [application] dies, the client dies; the client exits with a zero code if and only if [application] exited with a zero code. An UCSPI server closes descriptors 0 and 1 and waits for a client to connect to [address]. Upon accepting a connection, it spawns [application] with descriptor 0 reading from the connection and descriptor 1 writing to the connection. Meanwhile, and subsequently, it continues accepting connections to [address]. If the server receives signal SIGTERM, it exits with code 0; this does not affect any current connections. 4. Protocols Each UCSPI tool supports a protocol. A protocol definition provides three pieces of information: the name of the protocol; the format and meaning of [address]; and the environment variables set up by the tool. A protocol name is a sequence of one or more alphanumeric characters. See section 5 for information about the allocation of protocol names. A protocol definition always states the number of arguments taken by [address] and the allowed form for each argument. It also states an underlying communications medium to be used by the tool, and gives the interpretation of [address] in terms of that medium. Each tool passes the following environment variables to [application]: PROTO=[PROTO], the name of the supported protocol; zero or more variables beginning with [PROTO]LOCAL, as stated in the protocol definition; and zero or more variables beginning with [PROTO]REMOTE, as stated in the protocol definition. For clients, [PROTO]LOCAL variables give information about the client, and [PROTO]REMOTE variables give information about the server; vice versa for servers. Protocol definitions may specify environment variables that, in some situations, are not set. Those variables might be set upon entry to an UCSPI tool; if so, they must be unset, not passed along. A protocol definition may impose further requirements on clients and servers, such as supported options, forking behavior, and the nature of the descriptors passed to [application]. 5. Protocol management Public protocol definitions may be registered with me. I may refuse a registration request on the grounds of a namespace problem, but in that case I will suggest an acceptable replacement name. Protocol names beginning with x will be parcelled out to organizations that would like to define their own protocols. Protocol names beginning with X are reserved for experimental use.