# Module Rpc_portmapper

    module Rpc_portmapper: sig .. end

Portmapper version 2

Call the portmapper version 2. Note that version 2 is an older version (version 3 and 4 are called 'rpcbind'), but it is normally available.

The task of the portmapper is to map program numbers to port numbers. A RPC service that should be available in the whole network should:

- on startup: call the `set` procedure to establish a mapping of the own program number to the port that has been allocated previously
- on shutdown: call the `unset` procedure to remove the mapping (this is NEVER done automatically!)

To call an RPC service which is only known by its program number one should contact the portmapper using `getport` to find out the port where the service is actually listening.

    type t

represents a client for the portmapper

    val create : Rpc_client.connector -> t

Connects to the portmapper service listening on the given connector.

    val create_inet : string -> t

Connects to a portmapper listening on an Internet port. The argument is the hostname where the portmapper is running or its internet address. This function connects always to the port 111 on the given host; this is the standard for portmapper daemons.

    val shut_down : t -> unit

Shuts down the connection to the portmapper.

    val null : t -> unit

Calls the 'NULL' procedure of the portmapper. This procedure has no effect. You can use 'null' to determine whether a procedure call is possible or not.

    val set : t ->
           Rtypes.uint4 -> Rtypes.uint4 -> Rpc.protocol -> int -> bool

`set pm_client program_nr version_nr protocol port_nr`: Extends the mapping managed by the portmapper: The triple `(program_nr, version_nr, protocol)` is mapped to the given `port_nr`. It is not allowed to overwrite an existing mapping. The procedure returns `true` if the mapping has been extended and `false` otherwise. Note that it usually only possible to `set` a mapping on the local host.

    val unset : t ->
           Rtypes.uint4 -> Rtypes.uint4 -> Rpc.protocol -> int -> bool

`unset pm_client program_nr version_nr protocol port_nr`: removes the mapping. The procedure returns `true` if the mapping has been removed and `false` otherwise. Note that it usually only possible to `unset` a mapping on the local host.

    val getport : t -> Rtypes.uint4 -> Rtypes.uint4 -> Rpc.protocol -> int

`getport pm_client program_nr version_nr protocol`: finds out the port where the given service runs. Returns 0 if the service is not registered.

    val dump : t -> (Rtypes.uint4 * Rtypes.uint4 * Rpc.protocol * int) list

returns the list of known mappings. The quadrupels have the meaning `(program_nr, version_nr, protocol, port)`

    val callit : t ->
           Rpc_program.t -> string -> Xdr.xdr_value -> int * Xdr.xdr_value

`callit pm_client program_spec proc_name argument`: This is an alternate way of calling a remote procedure. Instead of directly invoking the procedure, the portmapper does it for you.

You must pass a program specification, the procedure name and the argument to `callit`. On return, you get the port of the service and the result of the procedure invocation.

Note that there are several disadvantages:

- Error conditions cannot be transmitted back from the portmapper. `callit` gets a timeout in this case.
- The portmapper uses always UDP. This means that the length of the messages that are exchanged is limited to a total of 8000 bytes.

It is NOT recommended to use `callit` for indirecting calls. The `callit` interface was designed for broadcasts and should only be used for this purpose. This implementation of a `callit` client cannot be used for broadcasts, however.

    val port_of_program : Rpc_program.t -> string -> Rpc.protocol -> int

`port_of_program program host protocol`: queries the portmapper running on `host` for the `program` registered for `protocol`. Returns the port number or fails if the number is not known.