Previous: Standard RPC Programs, Up: Standard RPC Programs
The (rpc rpc portmap) module implements the widespread
portmapper RPC program defined in RFC 1833 (see RFC 1833, Section 3). As the name suggests, the portmapper
interface allows servers to be queried for the association between an
RPC service and the port it is listening to. It also allows clients to
query the list of services registered.
In practice, most machines run a system-wide portmap daemon on
port 111 (TCP or UDP), and it is this server that is queried for
information about locally hosted RPC programs. The grpc-rpcinfo
program is a portmapper client that can be used to query a portmapper
server (see the grpc-rpcinfo tool)
Note that registering RPC programs with the portmapper is optional: it is basically a directory mechanism that allows servers to be located quite easily, but other existing mechanisms could be used for that purpose, e.g., decentralized service discovery (see service discovery with DNS-SD in Guile-Avahi).
The module exports client-side procedures, as returned by
make-synchronous-rpc-call (see Building an RPC Client), for
the various portmapper procedures. They are listed below.
Invoke the
nullRPC over port, ignoring arg, and return%void.
Invoke the
setRPC over port with argument arg. The invoked server should register the RPC program specified by arg, where arg must be an XDR struct (i.e., a Scheme list) containing these four elements: the RPC program number, its version number, its protocol and its port. The protocol number should be one ofIPPROTO_TCPorIPPROTO_UDP(see Network Sockets and Communication). An XDR boolean is returned, indicating whether the request successful.
Invoke the
unsetRPC over port with argument arg. The invoked server should unregister the RPC program specified by arg, where arg must have the same form as forportmapper-set. Again, an XDR boolean is returned, indicating whether the request was successful.
Invoke the
get-portRPC over port with argument arg, which must have the same form as previously mentioned (except that its port number is ignored). The invoked server returns an unsigned integer indicating the port of that RPC program.
Invoke the
dumpRPC over port, ignoring arg. The invoked server should return a list of 4-element lists describing the registered RPC programs. Those four element list are the same as forportmapper-setandportmapper-get, namely the RPC program number and version, its protocol and its port.
Invoke the call-it procedure over port. Quoting RFC 1833, this procedure “allows a client to call another remote procedure on the same machine without knowing the remote procedure's port number”. Concretely, it makes the portmapper invoke over UDP the procedure of the program matching the description in arg, where arg is an XDR struct (i.e., a Scheme list) containing an RPC program and version number, a procedure number, and an opaque array denoting the procedure arguments (an
xdr-variable-length-opaque-array).On success, it returns a struct consisting of the port number of the matching program and an opaque array representing the RPC reply. On failure, it does not return. Therefore, this synchronous call version may be inappropriate. We recommend that you do not use it.
The portmap module also provides convenience functions to
retrieve the symbolic name associated with common RPC program numbers.
The association between program numbers and their name is usually stored
in /etc/rpc on Unix systems and it can be parsed using the
read-rpc-service-list procedure.
Return a list of name-program pairs read from port (e.g., the /etc/rpc file), showing the connection between an RPC program human-readable name and its program number.