The pmap_getport routine returns the port number in host byte order not network byte order. For certain routines you may need to convert this value to network byte order using the htons routine. For example, the sockaddr_in structure requires that the port number be in network byte order.
x The port number of the service on the remote system. 0 No mapping exists or RPC could not contact the remote Portmapper service. In the latter case, the global variable rpc_createerr.cf_error contains the ONC RPC status.
The client interface to the Portmapper service for a remote call and broadcast service. This routine allows a program to do a lookup and call in one step.
#include <rpc/pmap_clnt.h>
enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr, u_long prognum, u_long versnum, u_long procnum, xdrproc_t inproc, char * in xdrproc_t outproc, char * out, struct timeval timeout, u_long *port );
addr
A pointer to a sockaddr_in structure containing the internet address of the host where the remote Portmapper resides.prognum
The program number associated with the remote procedure.versnum
The version number associated with the remote procedure.procnum
The procedure number associated with the remote procedure.inproc
The XDR routine used to encode the remote procedure's arguments.in
A pointer to the remote procedure's arguments.outproc
The XDR routine used to decode the remote procedure's results.out
A pointer to the remote procedure's results.timeout
A timeval structure describing the time allowed for the results to return to the client.port
A pointer to a location for the returned port number. Modified to the remote program's port number if the pmap_rmtcall routine succeeds.
A client interface to the Portmapper, which instructs the Portmapper on the host at the internet address *addr to make a call on your behalf to a procedure on that host. Use this procedure for a ping operation and nothing else. You can use the clnt_perrno routine to print any error message.
Note
If the requested procedure is not registered with the remote Portmapper, the remote Portmapper does not reply to the request. The call to pmap_rmtcall will eventually time out. The pmap_rmtcall does not perform authentication.
enum clnt_stat Returns the buffer containing the status of the operation.
Called by the server procedure to have the Portmapper create a mapping of the procedure's program and version number.
#include <rpc/pmap_clnt.h>
bool_t pmap_set(u_long prognum, u_long versnum, u_long protocol, u_short port);
prognum
The program number associated with the server procedure.versnum
The version number associated with the server procedure.protocol
The transport protocol that the server procedure uses. Specify either IPPROTO_UDP or IPPROTO_TCP.port
The port number associated with the server program.
A server interface to the Portmapper, which establishes a mapping between the triple [prognum,versnum,protocol] and port on the server's Portmapper service. The svc_register routine calls this routine to register the server with the local Portmapper.
TRUE Indicates success. FALSE Indicates failure.
Called by the server procedure to have the Portmapper delete a mapping of the procedure's program and version number.
#include <rpc/pmap_clnt.h>
bool_t pmap_unset(u_long prognum, u_long versnum);
prognum
The program number associated with the server procedure.versnum
The version number associated with the server procedure.
A server interface to the Portmapper, which destroys all mapping between the triple [prognum, versnum, *] and ports on the local host's Portmapper.
TRUE Indicates success. FALSE Indicates failure.
This chapter describes the server routines that allow C programs to receive procedure calls from client programs over the network.
Table 7-1 indicates the task that each routine performs.
| Routine | Task Category |
|---|---|
| registerrpc | Creates a server handle and registers the server program with the Portmapper. |
| seterr_reply | Fills in the error field in an RPC reply message with the specified error information. |
| svc_destroy | Destroys a server handle (macro). |
| svc_freeargs | Frees the memory allocated when RPC decoded the server procedure's arguments (macro). |
| svc_getargs | Decodes the server procedure's arguments (macro). |
| svc_getcaller | Returns the address of the client that called the server procedure (macro). |
| svc_getreqset | Reads data for each server connection. |
| svc_register | Registers the server program with the Portmapper. |
| svc_run | Waits for incoming RPC requests and dispatches to the appropriate service routine. |
| svc_sendreply | Sends the results of an RPC request to the client. |
| svc_unregister | Unregisters the server program with the Portmapper. |
| svcerr_auth | Sends an error message to the client indicating that the authentication information was not correctly formatted. |
| svcerr_decode | Sends an error message to the client indicating that the server could not decode the arguments. |
| svcerr_noproc | Sends an error message to the client indicating that the server does not implement the desired procedure. |
| svcerr_noprog | Sends an error message to the client indicating that the requested program is not available. |
| svcerr_progvers | Sends an error message to the client indicating that the requested version is not available. |
| svcerr_systemerr | Sends an error message to the client indicating that a system error occurred. |
| svcerr_weakauth | Sends an error message to the client indicating that the authentication information was correctly formatted but was insufficient. |
| svcraw_create | Creates a server handle for a client that shares the same program space. |
| svcfd_create | Creates a server handle for a specified TCP socket. |
| svctcp_create | Creates a server handle using the TCP protocol. |
| svcudp_bufcreate | Creates a server handle using buffered UDP transport. |
| svcudp_create | Creates a server handle using the UDP transport. |
| xprt_register | Adds the UDP or TCP socket associated with the specified server handle to the list of registered sockets. |
| xprt_unregister | Removes the UDP or TCP socket associated with the specified server handle from the list of sockets. |
| _authenticate | Authenticates an RPC request message. |
Obtains a unique systemwide procedure identification number.
#include <rpc/rpc.h>
int registerrpc(u_long prognum, u_long versnum, u_long procnum, char *(*progname)(), xdrproc_t inproc, xdrproc_t outproc );
prognum
The program number associated with the service procedure.versnum
The version number associated with the service procedure.procnum
The procedure number associated with the service procedure.progname
The address of the service procedure being registered with the ONC RPC service package.inproc
The XDR routine used to decode the service procedure's arguments.outproc
The XDR routine used to encode the service procedure's results.
The registerrpc routine performs the following tasks for a server:
- Creates a UDP server handle. See the svcudp_create routine for restrictions.
- Calls the svc_register routine to register the program with the Portmapper.
- Adds prognum, versnum, and procnum to an internal list of registered procedures. When the server receives a request, it uses this list to determine which routine to call.
A server should call registerrpc for every procedure it implements, except for the NULL procedure. If a request arrives for program prognum, version versnum, and procedure procnum, progname is called with a pointer to its parameters.
0 Indicates success. -1 Indicates failure.
Fills in the error text in a reply message.
#include <rpc/rpc.h>
void seterr_reply(struct rpc_msg *msg, struct rpc_err *error);
msg
A pointer to a reply message buffer.error
A pointer to an rpc_err structure containing the error associated with the reply message.
Given a reply message, seterr_reply fills in the error field.
None
A macro that frees the memory associated with an RPC server handle.
#include <rpc/rpc.h>
void svc_destroy(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
The svc_destroy routine returns all the private data structures associated with a server handle. If the server handle creation routine received the value RPC_ANYSOCK as the socket, svc_destroy closes the socket. Otherwise, your program must close the socket.
None
A macro that frees the memory allocated when the procedure's arguments were decoded.
#include <rpc/rpc.h>
bool_t svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.inproc
The XDR routine used to decode the service procedure's arguments.in
A pointer to the service procedure's decoded arguments.
The svc_destroy routine returns the memory that the svc_getargs routine allocated to hold the service procedure's decoded arguments. This routine calls the xdr_free routine.
TRUE Success; memory successfully deallocated. FALSE Failure; memory not deallocated.
A macro that decodes the service procedure's arguments.
#include <rpc/rpc.h>
bool_t svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.inproc
The XDR routine used to decode the service procedure's arguments.in
A pointer to the service procedure's decoded arguments.
This routine calls the specified XDR routine to decode the arguments passed to the service procedure.
TRUE Successfully decoded. FALSE Decoding unsuccessful.
A macro that returns the address of the client that called the service procedure.
#include <rpc/rpc.h>
struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
This routine returns a sockaddr_in structure containing the internet address of the RPC client routine that called the service procedure.
struct sockaddr_in A pointer to the socket descriptor.
Returns data for each server connection.
#include <rpc/rpc.h>
void svc_getreqset(fd_set *rdfds);
rdfds
A pointer to the read file descriptor bit mask modified by the select routine.
The svc_getreqset routine is for servers that implement custom asynchronous event processing or that do not use the svc_run routine. You may only use svc_fdset when the server does not use svc_run.You are unlikely to call this routine directly, because the svc_run routine calls it. However, there are times when you cannot call svc_run. For example, suppose a program services RPC requests and reads or writes to another socket at the same time. The program cannot call svc_run. It must call select and svc_getreqset.
The server calls svc_getreqset when a call to the select system call determines the server has received one or more RPC requests. The svc_getreqset routine reads in data for each server connection, then calls the server program to handle the data.
The svc_getreqset routine does not return a value. It finishes executing after all sockets associated with the variable rdfds have been serviced.
You may use the global variable svc_fdset with svc_getreqset. The svc_fdset variable is the RPC server's read file descriptor bit mask.
To use svc_fdset:
- Copy the global variable svc_fdset into a temporary variable.
- Pass the temporary variable to the select routine. The select routine overwrites the variable and returns it.
- Pass the temporary variable to the svc_getreqset routine.
#define MAXSOCK 10
int readfds[ MAXSOCK+1], /* sockets to select from*/
i, j;
for(i = 0, j = 0; i << MAXSOCK; i++)
if((svc_fdset[i].sockname != 0) && (svc_fdset[i].sockname != -1))
readfds[j++] = svc_fdset[i].sockname;
readfds[j] = 0; /* list of sockets ends with a zero */
switch(select(0, readfds, 0, 0, 0))
{
case -1: /* an error happened */
case 0: /* time out */
break;
default: /* 1 or more sockets ready for reading */
errno = 0;
svc_getreqset(readfds);
if( errno == ENETDOWN || errno == ENOTCONN)
sys$exit( SS$_THIRDPARTY);
}
None
Registers the server program with the Portmapper service.
#include <rpc/rpc.h>
bool_t svc_register(SVCXPRT *xprt, u_long prognum, u_long versnum, void (*dispatch)(), u_long protocol);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.prognum
The program number associated with the server procedure.versnum
The version number associated with the server procedure.dispatch
The address of the service dispatch procedure that the server procedure calls. The procedure dispatch has the following form:void dispatch(request, xprt) struct svc_req *request; SVCXPRT *xprt;The svc_run and svc_getreqset call the dispatch routine.
protocol
The protocol that the server procedure uses. Values for this parameter are zero, IPPROTO_UDP, or IPPROTO_TCP. If protocol is zero, the service is not registered with the Portmapper service.
Associates prognum and versnum with the service dispatch procedure dispatch. If protocol is non-zero, then a mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is also established with the local Portmapper service.
TRUE Indicates success. FALSE Indicates failure.
Waits for incoming RPC requests and calls the svc_getreqset routine to dispatch to the appropriate RPC server program.
#include <rpc/rpc.h>
void svc_run();
None
The svc_run routine calls the select routine to wait for RPC requests. When a request arrives, svc_run calls the svc_getreqset routine. Then svc_run calls the select routine again.The svc_run routine never returns.
You may use the global variable svc_fdset with the svc_run routine. See the svc_getreqset routine for more information on svc_fdset.
Never returns
Sends the results of a remote procedure call to an RPC client.
#include <rpc/rpc.h>
bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.outproc
The XDR routine used to encode the server procedure's results.out
A pointer to the server procedure's results.
Called by an ONC RPC service's dispatch routine to send the results of a remote procedure call.
TRUE Indicates success. FALSE Indicates failure.
Calls the Portmapper to unregister the specified program and version for all protocols. The program and version are removed from the list of active servers.
#include <rpc/rpc.h>
void svc_unregister(u_long prognum, u_long versnum);
prognum
The program number associated with the server procedure.versnum
The version number associated with the server procedure.
Removes all mapping of the double [prognum, versnum] to dispatch routines, and of the triple [prognum, versnum, *] to port number.
None
Sends an authentication error to the client.
#include <rpc/rpc.h>
void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.why
The reason for the authentication error.
Called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error.
None
Sends an error code to the client indicating that the server procedure cannot decode the client's arguments.
#include <rpc/rpc.h>
void svcerr_decode(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
Called by a service dispatch routine that cannot successfully decode its parameters. See also the svc_getargs routine.
None
Sends an error code to the client indicating that the server program does not implement the requested procedure.
#include <rpc/rpc.h>
void svcerr_noproc(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
Called by a service dispatch routine that does not implement the procedure number that the client requested.
None
Sends an error code to the client indicating that the server program is not registered with the Portmapper.
#include <rpc/rpc.h>
void svcerr_noprog(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
Called when the desired program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a server is not registered. Therefore, service implementors usually do not use this routine.
None
Sends an error code to the client indicating that the requested program is registered with the Portmapper but the requested version of the program is not registered.
#include <rpc/rpc.h>
void svcerr_progvers(SVCXPRT *xprt, u_long low_vers, u_long high_vers);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.low_vers
The lowest version of the requested program that the server supports.high_vers
The highest version of the requested program that the server supports.
Called when the desired version of a program is not registered with the ONC RPC package. Generally, the Portmapper informs the client when a requested program version is not registered. Therefore, service implementors usually do not use this routine.
None
Sends an error code to the client indicating that the an error occurred that is not handled by the protocol being used.
#include <rpc/rpc.h>
void svcerr_systemerr(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine.
None
Sends an error code to the client indicating that an authentication error occurred. The authentication information was correct but was insufficient.
#include <rpc/rpc.h>
void svcerr_weakauth(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient (but correct) authentication parameters. The routine calls svcerr_auth (xprt, AUTH_TOOWEAK).
None
Creates a server handle for memory-based ONC RPC for simple testing and timing.
#include <rpc/rpc.h>
SVCXPRT *svcraw_create();
None
Creates a in-program ONC RPC service transport, to which it returns a pointer. The transport is really a buffer within the process's address space, so the corresponding client should live in the same address space; see the clntraw_create routine. The svcraw_create and clntraw_create routines allow simulation and acquisition of ONC RPC overheads (such as round-trip times), without any kernel interference.
SVCXPRT* A pointer to an RPC server handle for the in-memory transport. NULL Indicates failure.
Creates an RPC server handle using the specified open file descriptor.
#include <rpc/rpc.h>
SVCXPRT *svcfd_create(int fd, u_int sendsize, u_int recvsize);
fd
The number of an open file descriptor.sendsize
The size of the send buffer. If you specify 0, the routine chooses a suitable default.recvsize
The size of the receive buffer. If you specify 0, the routine chooses a suitable default.
Creates an RPC server handle using the specified TCP socket, to which it returns a pointer. The server should call the svcfd_create routine after it accepts an incoming TCP connection.
SVCXPRT* A pointer to the server handle. NULL Indicates failure.
Creates an ONC RPC server handle for a TCP/IP connection.
#include <rpc/rpc.h>
SVCXPRT *svctcp_create(int sock, u_int sendsize, u_int recvsize);
sock
The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port.sendsize
The size of the send buffer. If you specify 0, the routine chooses a suitable default.recvsize
The size of the receive buffer. If you specify 0, the routine chooses a suitable default.
Creates an RPC server handle using the TCP/IP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls).
SVCXPRT* A pointer to the server handle. NULL Indicates failure.
Creates an ONC RPC server handle for a buffered I/O UDP connection.
#include <rpc/rpc.h>
SVCXPRT *svcudp_bufcreate(int sock, u_int sendsize, u_int recvsize);
sock
The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock.sendsize
The size of the send buffer. If you specify 0, the routine chooses a suitable default.recvsize
The size of the receive buffer. If you specify 0, the routine chooses a suitable default.
Creates an RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls).
SVCXPRT* A pointer to the server handle. NULL Indicates failure.
Creates an ONC RPC server handle for a non-buffered I/O UDP connection.
#include <rpc/rpc.h>
SVCXPRT *svcudp_create(int sock);
sock
The socket with which the connection is associated. If sock is RPC_ANYSOCK, then this routine opens a new socket and sets sock.
Creates an RPC server handle using the UDP transport, to which it returns a pointer. Upon completion, xprt->xp_sock is the transport's socket descriptor, and xprt->xp_port is the transport's port number. The service is automatically registered as a transporter (thereby including its socket in svc_fds such that its socket descriptor is included in all RPC select system calls).
Note
Since UDP/IP-based ONC RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results.
SVCXPRT* A pointer to the server handle. NULL Indicates failure.
Adds a socket associated with an RPC server handle to the list of registered sockets.
#include <rpc/rpc.h>
void xprt_register(SVCXPRT *xprt);
xprt
A pointer to an RPC server handle created by any of the server handle creation routines.
Activation of a transport handle involves setting the most appropriate bit for the socket associated with xprt in the svc_fds mask. When svc_run() is invoked, activity on the transport handle is eligible to be processed by the server.
Previous | Next | Contents