rpc_soc(3N) rpc_soc(3N)
NAME
rpc_soc: authdes_create(), authunix_create(), authunix_create_default(), callrpc(), clnt_broadcast(), clntraw_create(), clnttcp_create(),
clntudp_bufcreate(), clntudp_create(), get_myaddress(), pmap_getmaps(), pmap_getport(), pmap_rmtcall(), pmap_set(), pmap_unset(), register-
rpc(), svc_fds, svc_getcaller(), svc_getreq(), svc_register(), svc_unregister(), svcfd_create(), svcraw_create(), svctcp_create(),
svcudp_bufcreate(), svcudp_create(), xdr_authunix_parms() - obsolete library routines for RPC
SYNOPSIS
DESCRIPTION
RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a
request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends
back a reply. Finally, the procedure call returns to the client.
NOTE: The routines described in this manual page have been superseded by other routines. The preferred routine is given after the
description of the routine. New programs should use the preferred routines, as support for the older interfaces may be dropped in
future releases.
The HP-UX implementation of RPC only supports the X/Open Transport Interface (XTI). Applications that are written using the Transport
Layer Interface (TLI) and wish to use RPC, must convert their application to XTI.
File Descriptors
Transport independent RPC uses XTI as its transport interface instead of sockets.
Some of the routines described in this section (such as take a pointer to a file descriptor as one of the parameters. If the user passed
as the file descriptor, then the routine will return a TLI file descriptor and not a socket.
Routines
The following routines require that the header be included. The symbol should be defined so that the appropriate function declarations for
the old interfaces are included through the header files.
is the first of two routines which interface to the RPC
secure authentication system, known as DES authentication. The second is below. Note: the keyserver daemon keyserv(1M) must
be running for the DES authentication system to work.
used on the client side, returns an authentication handle that will enable the use of the secure authentication system. The
first parameter name is the network name, or netname, of the owner of the server process. This field usually represents a
hostname derived from the utility routine but could also represent a user name using (see secure_rpc(3N)). The second field
window is a window on the validity of the client credential, given in seconds. A small window is more secure than a large
one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third
parameter syncaddr is optional. If it is NULL, then the authentication system will assume that the local clock is always in
sync with the server's clock, and will not attempt resynchronizations. If an address is supplied, however, then the system
will use the address for consulting the remote time service whenever resynchronization is required. This parameter is usu-
ally the address of the RPC server itself. The final parameter ckey is also optional. If it is NULL, then the authentica-
tion system will generate a random DES key to be used for the encryption of credentials. If it is supplied, however, then it
will be used instead.
Warning: this routine exists for backward compatibility only, and is made obsolete by (see secure_rpc(3N)).
Create and return an RPC authentication handle that contains
UX authentication information. The parameter host is the name of the machine on which the information was created; uid is
the user's user ID; gid is the user's current group ID; grouplen and gidlistp refer to a counted array of groups to which the
user belongs.
Warning: it is not very difficult to impersonate a user.
Warning: this routine exists for backward compatibility only, and is made obsolete by (see rpc_clnt_auth(3N)).
Call with the appropriate parameters.
Warning: this routine exists for backward compatibility only, and is made obsolete by (see rpc_clnt_auth(3N)).
Call the remote procedure associated with
prognum, versnum, and procnum on the machine, host. The parameter inproc is used to encode the procedure's parameters, and
outproc is used to decode the procedure's results; in is the address of the procedure's argument, and out is the address of
where to place the result(s). This routine returns if it succeeds, or the value of cast to an integer if it fails. The rou-
tine (see rpc_clnt_calls(3N)) is handy for translating failure statuses into messages.
Warning: you do not have control of timeouts or authentication using this routine. This routine exists for backward compati-
bility only, and is made obsolete by (see rpc_clnt_calls(3N)).
Like except the call message is broadcast to all locally connected broadcast nets. Each time the caller receives a response, this
routine calls whose form is:
where out is the same as out passed to except that the remote procedure's output is decoded there; addr points to the address
of the machine that sent the results. If returns waits for more replies; otherwise it returns with appropriate status. If
is NULL, returns without waiting for any replies.
Warning: broadcast packets are limited in size to the maximum transfer unit of the transports involved. For Ethernet, the
callers argument size is approximately 1500 bytes. Since the call message is sent to all connected networks, it may poten-
tially lead to broadcast storms. uses credentials by default (see rpc_clnt_auth(3N)).
Warning: this routine exists for backward compatibility only, and is made obsolete by (see rpc_clnt_calls(3N)).
This routine creates an internal, memory-based RPC
client for the remote program prognum, version versnum. The transport used to pass messages to the service is actually a
buffer within the process's address space, so the corresponding RPC server should live in the same address space; see
svcraw_create(3N). This allows simulation of RPC and acquisition of RPC overheads, such as round trip times, without any
kernel interference. This routine returns NULL if it fails.
Warning: this routine exists for backward compatibility only. It has the same functionality as (see rpc_clnt_create(3N)),
which obsoletes it.
This routine creates an RPC client for the remote program
prognum, version versnum; the client uses TCP/IP as a transport. The remote program is located at Internet address addr. If
is then it is set to the actual port that the remote program is listening on (the remote service is consulted for this infor-
mation). The parameter *fdp is a file descriptor, which may be open and bound; if it is then this routine opens a new one
and sets *fdp. Refer to the section for more information. Since TCP-based RPC uses buffered I/O, the user may specify the
size of the send and receive buffers with the parameters sendsz and recvsz; values of choose suitable defaults. This routine
returns NULL if it fails.
Warning: this routine exists for backward compatibility only. or (see rpc_clnt_create(3N)) should be used instead.
Create a client handle for the remote program
prognum, on versnum; the client uses UDP/IP as the transport. The remote program is located at the Internet address addr.
If is it is set to the actual port on which the remote program is listening on (the remote service is consulted for this
information). The parameter *fdp is a file descriptor, which may be open and bound. If it is then this routine opens a new
one and sets *fdp. Refer to the section for more information. The UDP transport resends the call message in intervals of
wait time until a response is received or until the call times out. The total time for the call to time out is specified by
(see rpc_clnt_calls(3N)). If successful it returns a client handle, otherwise it returns NULL. The error can be printed
using the (see rpc_clnt_create(3N)) routine.
The user can specify the maximum packet size for sending and receiving by using sendsz and recvsz arguments for UDP-based RPC
messages.
If is and the requested version number versnum is not registered with the remote portmap service, it returns a handle if at
least a version number for the given program number is registered. The version mismatch is discovered by a later (see
rpc_clnt_calls(3N)).
Warning: this routine exists for backward compatibility only. or (see rpc_clnt_create(3N)) should be used instead.
This routine creates an RPC client handle for the remote program
prognum, version versnum; the client uses UDP/IP as a transport. The remote program is located at Internet address addr. If
is then it is set to the actual port that the remote program is listening on (the remote service is consulted for this infor-
mation). The parameter *fdp is a file descriptor, which may be open and bound; if it is then this routine opens a new one
and sets *fdp. Refer to the section for more information. The UDP transport resends the call message in intervals of time
until a response is received or until the call times out. The total time for the call to time out is specified by (see
rpc_clnt_calls(3N)). returns a client handle on success, otherwise it returns NULL. The error can be printed using the (see
rpc_clnt_create(3N)) routine.
Since UDP-based 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.
Warning: this routine exists for backward compatibility only. or (see rpc_clnt_create(3N)) should be used instead.
Places the local system's IP address into
*addr, without consulting the library routines that deal with The port number is always set to
Warning: this routine is only intended for use with the RPC library. It returns the local system's address in a form compat-
ible with the RPC library, and should not be taken as the system's actual IP address. In fact, the *addr buffer's host
address part is actually zeroed. This address may have only local significance and should not be assumed to be an address
that can be used to connect to the local system by remote systems or processes.
Warning: this routine remains for backward compatibility only. The routine (see netdir(3N)) should be used with the name to
retrieve the local system's network address as a netbuf structure.
A user interface to the
service, which returns a list of the current RPC program-to-port mappings on the host located at IP address addr. This rou-
tine can return NULL. The command uses this routine.
Warning: this routine exists for backward compatibility only, enhanced functionality is provided by (see rpcbind(3N)).
A user interface to the
service, which returns the port number on which waits a service that supports program prognum, version versnum, and speaks
the transport protocol associated with protocol. The value of protocol is most likely or A return value of means that the
mapping does not exist or that the RPC system failed to contact the remote service. In the latter case, the global variable
contains the RPC status.
Warning: this routine exists for backward compatibility only, enhanced functionality is provided by (see rpcbind(3N)).
Request that the
on the host at IP address *addr make an RPC on the behalf of the caller to a procedure on that host. *portp is modified to
the program's port number if the procedure succeeds. The definitions of other parameters are discussed in and (see
rpc_clnt_calls(3N)).
This procedure is only available for the UDP transport.
If the requested remote procedure is not registered with the remote then no error response is returned and the call times
out. Also, no authentication is done.
Warning: this routine exists for backward compatibility only, enhanced functionality is provided by (see rpcbind(3N)).
A user interface to the
service, that establishes a mapping between the triple [prognum, versnum, protocol] and port on the machine's service. The
value of protocol may be or Formerly, the routine failed if the requested port was found to be in use. Now, the routine only
fails if it finds that port is still bound. If port is not bound, the routine completes the requested registration. This
routine returns if it succeeds, otherwise. Automatically done by
Warning: this routine exists for backward compatibility only, enhanced functionality is provided by (see rpcbind(3N)).
A user interface to the
service, which destroys all mapping between the triple [prognum, versnum, all-protocols] and port on the machine's service.
This routine returns if it succeeds, otherwise.
Warning: this routine exists for backward compatibility only, enhanced functionality is provided by (see rpcbind(3N)).
A global variable reflecting the RPC
service side's read file descriptor bit mask; it is suitable as a parameter to the call. This is only of interest if a ser-
vice implementor does not call but rather does his own asynchronous event processing. This variable is read-only (do not
pass its address to yet it may change after calls to or any creation routines. Similar to but limited to 32 descriptors.
Warning: this interface is made obsolete by (see rpc_svc_calls(3N)).
This routine returns the network address, represented as a
of the caller of a procedure associated with the RPC service transport handle, xprt.
Warning: this routine exists for backward compatibility only, and is obsolete. The preferred interface is (see
rpc_svc_reg(3N)), which returns the address as a
This routine is only of interest if a service implementor does not call
but instead implements custom asynchronous event processing. It is called when the call has determined that an RPC request
has arrived on some RPC file descriptors; rdfds is the resultant read file descriptor bit mask. The routine returns when all
file descriptors associated with the value of rdfds have been serviced. This routine is similar to but is limited to 32
descriptors.
Warning: this interface is made obsolete by
Create a service on top of any open and bound descriptor.
Typically, this descriptor is a connected file descriptor for a stream protocol. Refer to the section for more information.
sendsz and recvsz indicate sizes for the send and receive buffers. If they are a reasonable default is chosen.
Warning: this interface is made obsolete by (see rpc_svc_create(3N)).
This routine creates an internal, memory-based RPC
service transport, to which it returns a pointer. The transport is really a buffer within the process' address space, so the
corresponding RPC client should live in the same address space; see clntraw_create(3N). This routine allows simulation of
RPC and acquisition of RPC overheads (such as round trip times), without any kernel interference. This routine returns NULL
if it fails.
Warning: this routine exists for backward compatibility only, and has the same functionality of (see rpc_svc_create(3N)),
which obsoletes it.
This routine creates a TCP/IP-based RPC
service transport, to which it returns a pointer. The transport is associated with the file descriptor fd, which may be in
which case a new file descriptor is created. If the file descriptor is not bound to a local TCP port, then this routine
binds it to an arbitrary port. Refer to the section for more information. Upon completion, is the transport's file descrip-
tor, and is the transport's port number. This routine returns NULL if it fails. Since TCP-based RPC uses buffered I/O,
users may specify the size of buffers; values of choose suitable defaults.
Warning: this routine exists for backward compatibility only. or (see rpc_svc_create(3N)) should be used instead.
This routine creates a UDP/IP-based RPC
service transport, to which it returns a pointer. The transport is associated with the file descriptor fd. If fd is then a
new file descriptor is created. If the file descriptor is not bound to a local UDP port, then this routine binds it to an
arbitrary port. Upon completion, is the transport's file descriptor, and is the transport's port number. Refer to the sec-
tion for more information. This routine returns NULL if it fails.
The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the sendsz and recvsz
parameters.
Warning: this routine exists for backward compatibility only. or (see rpc_svc_create(3N)) should be used instead.
This routine creates a UDP/IP-based RPC
service transport, to which it returns a pointer. The transport is associated with the file descriptor fd, which may be in
which case a new file descriptor is created. If the file descriptor is not bound to a local UDP port, then this routine
binds it to an arbitrary port. Upon completion, is the transport's file descriptor, and is the transport's port number.
This routine returns NULL if it fails.
Since UDP-based 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.
Warning: this routine exists for backward compatibility only. or (see rpc_svc_create(3N)) should be used instead.
Register program
prognum, procedure procname, and version versnum with the RPC service package. If a request arrives for program prognum,
version versnum, and procedure procnum, procname is called with a pointer to its parameter(s); procname should return a
pointer to its static result(s). inproc is used to decode the parameters while outproc is used to encode the results. This
routine returns if the registration succeeded, otherwise.
must be called after all the services are registered.
Warning: this routine exists for backward compatibility only, and is made obsolete by (see rpc_svc_calls(3N)).
Associates
prognum and versnum with the service dispatch procedure, dispatch. If protocol is the service is not registered with the
service. If protocol is non-zero, then a mapping of the triple [prognum, versnum, protocol] to is established with the local
service (generally, protocol is or The procedure dispatch has the following form:
The routine returns if it succeeds, and otherwise.
Warning: this routine exists for backward compatibility only; enhanced functionality is provided by (see rpc_svc_calls(3N)).
Remove all mapping of the double
[prognum, versnum] to dispatch routines, and of the triple [prognum, versnum, all-protocols] to port number from
Warning: this routine exists for backward compatibility, enhanced functionality is provided by (see rpc_svc_calls(3N)).
Used for describing UNIX credentials.
This routine is useful for users who wish to generate these credentials without using the RPC authentication package.
Warning: this routine exists for backward compatibility only, and is made obsolete by (see rpc_xdr(3N)).
MULTITHREAD USAGE
Thread Safe: No
Cancel Safe: No
Async-cancel Safe: No
Async-signal Safe: No
These interfaces are unsafe in multithreaded applications. Unsafe interfaces should be called only from the main thread.
SEE ALSO
keyserv(1M), rpcbind(1M), rpcinfo(1M), rpc(3N), rpc_clnt_auth(3N), rpc_clnt_calls(3N), rpc_clnt_create(3N), rpc_svc_calls(3N), rpc_svc_cre-
ate(3N), rpc_svc_err(3N), rpc_svc_reg(3N), rpcbind(3N), secure_rpc(3N), select(2).
OBSOLETE rpc_soc(3N)