Previous: Standard RPC Programs, Up: Standard RPC Programs [Contents][Index]
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 in Using Avahi in Guile Scheme Programs).
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 null RPC over port, ignoring arg, and
return %void.
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 in The GNU Guile Reference Manual). An XDR
boolean is returned, indicating whether the request successful.
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.
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.
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.
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.
Lookup RPC program numbered program in service-list (a list as
returned by read-rpc-service-list) and return its human-readable
name.
Lookup RPC program named program in service-list (a list as
returned by read-rpc-service-list) and return its RPC program
number.
Previous: Standard RPC Programs, Up: Standard RPC Programs [Contents][Index]