rpc_soc(3N)rpc_soc(3N)NAME
rpc_soc: authdes_create(), authunix_create(), authunix_cre‐
ate_default(), callrpc(), clnt_broadcast(), clntraw_create(),
clnttcp_create(), clntudp_bufcreate(), clntudp_create(), get_myad‐
dress(), pmap_getmaps(), pmap_getport(), pmap_rmtcall(), pmap_set(),
pmap_unset(), registerrpc(), svc_fds, svc_getcaller(), svc_getreq(),
svc_register(), svc_unregister(), svcfd_create(), svcraw_create(),
svctcp_create(), svcudp_bufcreate(), svcudp_create(), xdr_authu‐
nix_parms() - obsolete library routines for RPC
SYNOPSISDESCRIPTION
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 applica‐
tion 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 authentica‐
tion. 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 fre‐
quency 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 sup‐
plied, however, then the system will use the address for
consulting the remote time service whenever resynchro‐
nization is required. This parameter is usually the
address of the RPC server itself. The final parameter
ckey is also optional. If it is NULL, then the authenti‐
cation 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 param‐
eters, 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 routine (see
rpc_clnt_calls(3N)) is handy for translating failure sta‐
tuses into messages.
Warning: you do not have control of timeouts or authenti‐
cation using this routine. This routine exists for back‐
ward compatibility only, and is made obsolete by (see
rpc_clnt_calls(3N)).
Like except the call message is broadcast to all locally con‐
nected 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 potentially 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 simu‐
lation 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 ser‐
vice 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. 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 trans‐
port. 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 ser‐
vice 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 speci‐
fied 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 ser‐
vice 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 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 proce‐
dures 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 compatible 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 con‐
nect 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 routine can return NULL. The command uses this rou‐
tine.
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 proto‐
col. 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 dis‐
cussed 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 com‐
pletes 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 suit‐
able as a parameter to the call. This is only of inter‐
est if a service implementor does not call but rather
does his own asynchronous event processing. This vari‐
able 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 ser‐
vice 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 process‐
ing. 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 interfer‐
ence. This routine returns NULL if it fails.
Warning: this routine exists for backward compatibility
only, and has the same functionality of (see rpc_svc_cre‐
ate(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 cre‐
ated. 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 comple‐
tion, is the transport's file descriptor, 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 trans‐
port's port number. Refer to the section for more infor‐
mation. 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 cre‐
ated. 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 proce‐
dures 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 regis‐
tration 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 map‐
ping 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 ALSOkeyserv(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_create(3N), rpc_svc_err(3N), rpc_svc_reg(3N), rpcbind(3N),
secure_rpc(3N), select(2).
OBSOLETE rpc_soc(3N)
