Previous: Standard RPC Programs, Up: Standard RPC Programs


4.4.1 The Portmapper Program

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.

— Scheme Procedure: portmapper-null arg xid port

Invoke the null RPC over port, ignoring arg, and return %void.

— Scheme Procedure: portmapper-set arg xid port

Invoke the set RPC 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 of IPPROTO_TCP or IPPROTO_UDP (see Network Sockets and Communication). An XDR boolean is returned, indicating whether the request successful.

— Scheme Procedure: portmapper-unset arg xid port

Invoke the unset RPC over port with argument arg. The invoked server should unregister the RPC program specified by arg, where arg must have the same form as for portmapper-set. Again, an XDR boolean is returned, indicating whether the request was successful.

— Scheme Procedure: portmapper-get-port arg xid port

Invoke the get-port RPC 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.

— Scheme Procedure: portmapper-dump arg xid port

Invoke the dump RPC 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 for portmapper-set and portmapper-get, namely the RPC program number and version, its protocol and its port.

— Scheme Procedure: portmapper-call-it arg xid 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.

— Scheme Procedure: read-rpc-service-list port

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.

— Scheme Procedure: lookup-rpc-service-name service-list program

Lookup RPC program numbered program in service-list (a list as returned by read-rpc-service-list) and return its human-readable name.

— Scheme Procedure: lookup-rpc-service-number service-list program

Lookup RPC program named program in service-list (a list as returned by read-rpc-service-list) and return its RPC program number.