portmap(3C)

NAME

pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, pmap_unset, xdr_pmap, xdr_pmaplist − library of routines for RPC binder services

SYNOPSIS

#include <rpc/rpc.h>

/* pmap_getmaps() */
struct pmaplist *
pmap_getmaps(addr)
struct sockaddr_in *addr;

/* pmap_getport() */
u_short
pmap_getport(addr, prognum, versnum, protocol)
struct sockaddr_in *addr;
u_long prognum, versnum, protocol;

/* pmap_rmtcall */
enum clnt_stat
pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in,
outproc, out, timeout, portp)
struct sockaddr_in *addr;
u_long prognum, versnum, procnum;
xdrproc_t inproc, outproc;
char *in, *out;
struct timeval timeout;
u_long *portp;

/* pmap_set */
bool_t
pmap_set(prognum, versnum, protocol, port)
u_long prognum, versnum;
int protocol;
u_short port;

/* pmap_unset */
bool_t
pmap_unset(prognum, versnum)
u_long prognum, versnum;

/* xdr_pmap */
bool_t
xdr_pmap(xdrs, regp)
XDR *xdrs;
struct pmap *regp;

/* xdr_pmaplist */
bool_t
xdr_pmaplist(xdrs, rp)
XDR *xdrs;
struct pmaplist *rp;

DESCRIPTION

portmap() maintains a list of mappings between programs and their universal addresses. These portmap() routines allow C client programs to make procedure calls to the RPC binder service.

Routines

To use these routines, the C programs must include the header file <rpc.h>.

pmap_getmaps() Return a list of the current RPC program-to-address mappings on the host located at the registered IP address, *addr. This routine returns NULL if the remote portmap service could not be contacted. The command rpcinfo −p uses this routine (see rpcinfo(1M) for more information).

pmap_getport() Return the port number of a waiting service. The remote (waiting) service supports the program number, prognum , version number, versnum , and speaks the transport protocol, protocol . The value of protocol can be IPPROTO_UDP, indicating that UDP/IP protocol is being used, or IPPROTO_TCP, indicating that TCP/IP protocol is being used. The address is returned to portmap() in addr, and should be a preallocated IP address. This routine returns a value of zero if the RPC binder service does not find a mapping for the service or if the RPC system fails to contact the remote portmap service. In the latter case, the global variable rpc_createer , which is documented in rpc_clnt_create(3C), contains the RPC status. The call returns a port number if any version number is registered for the referenced program number (even if the requested version number is not registered).

Note: pmap_getport() returns the port number in host-byte order. Some other network routines may require the port number in network-byte order. For example, if the port number is used as part of the sockaddr_in structure, then it should be converted to network-byte order using htons().

pmap_rmtcall() Request that the portmap on the host at IP address, *addr, make an RPC on the behalf of the caller to a procedure on that host. *portp is changed to the program’s port number if the procedure succeeds. The definitions of other parameters are provided in the descriptions for callrpc() and clnt_call() (see rpc_clnt_calls(3C)).

Warning: If the requested remote procedure is not registered with the remote portmap, no error response is returned and the call times out. Also, no authentication is done.

pmap_set() Register a mapping between [prognum,versnum,protocol] and port on the local machine’s portmap service. The value of protocol can be IPPROTO_UDP, indicating that UDP/IP protocol is being used, or IPPROTO_TCP, indicating that TCP/IP protocol is being used. This routine allows servers to register themselves with the local portmap(), and is done automatically by svc_register(). It returns TRUE if it succeeds; otherwise, it returns FALSE.

pmap_unset() Deregister all mappings between [prognum,versnum,*] and ports on the local machine’s portmap service. This routine allows servers to deregister themselves with the local portmap(). It returns TRUE if it succeeds; otherwise, it returns FALSE.

xdr_pmap() Create parameters to various portmap() procedures, externally. This routine allows users to generate portmap() parameters without using the pmap interface. It returns TRUE if it succeeds; otherwise, it returns FALSE.

xdr_pmaplist() Create a list of port mappings, externally. This routine allows users to generate portmap() parameters without using the pmap interface. It returns TRUE if it succeeds; otherwise, it returns FALSE.

AUTHOR

portmap() and rpc() were developed by Sun Microsystems, Inc.

Museum