Client routines allow C programs to make procedure calls to
server programs across the network.
Important: In order to maintain uniqueness for the OpenVMS HELP
utility, some client routines have a "_#" appended at the end. Do
not use the "_#" when coding the routine in a program.
1 – auth_destroy
A macro that frees the memory associated with the authentication
handle created by the authnone_create and authunix_create
routines.
Format
#include <rpc/rpc.h>
void auth_destroy(AUTH *auth_handle)
1.1 – Arguments
auth_handle
An RPC authentication handle created by the authnone_create,
authunix_create, or authunix_create_default routine.
1.2 – Description
Frees the memory associated with the AUTH data structure created
by the authnone_create, authunix_create, or authunix_create_
default routine. Be careful not to reference the data structure
after calling this routine.
1.3 – Return Values
None
2 – authnone_create
Creates an authentication handle for passing null credentials and
verifiers to remote systems.
Format
#include <rpc/rpc.h>
AUTH *authnone_create ( )
2.1 – Arguments
None
2.2 – Description
Creates and returns an authentication handle that passes
null authentication information with each remote procedure
call. Use this routine if the server process does not require
authentication information. RPC uses this routine as the default
authentication routine unless you create another authentication
handle using either the authunix_create or authunix_create_
default routine.
2.3 – Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
3 – authunix_create
Creates and returns an RPC authentication handle that contains
UNIX-style authentication information.
Format
#include <rpc/rpc.h>
AUTH *authunix_create(char *host, int uid, int gid, int len,
int *aup_gids );
3.1 – Arguments
host
Pointer to the name of the host on which the information was
created. This is usually the name of the system running the
client process.
uid
The user's user identification.
gid
The user's current group.
len
The number of elements in aup_gids array.
NOTE
This parameter is ignored by the product's RPC
implementation.
aup_gids
A pointer to an array of groups to which the user belongs.
NOTE
This parameter is ignored by the product's RPC
implementation.
3.2 – Description
Implements UNIX-style authentication parameters. The client uses
no encryption for its credentials and only sends null verifiers.
The server sends back null verifiers or, optionally, a verifier
that suggests a new shorthand for the credentials.
3.3 – Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
4 – authunix_create_default
Returns a default authentication handle.
Format
#include <rpc/rpc.h>
AUTH *authunix_create_default( )
4.1 – Arguments
None
4.2 – Description
Calls the authunix_create routine with the local host name,
effective process ID and group ID, and the process default
groups.
4.3 – Return Values
AUTH * Authentication handle containing the pertinent
information.
NULL Indicates allocation of AUTH handle failed.
4.4 – Examples
1.auth_destroy(client->cl_auth)
client->cl_auth = authunix_create_default();
This example overrides the default authnone_create action. The
client handle, client, is returned by the clnt_create, clnt_
create_vers, clnttcp_create, or clntudp_create routine.
5 – callrpc
Executes a remote procedure call.
Format
#include <rpc/rpc.h>
int callrpc(char *host, u_long prognum, u_long versnum, u_long
procnum, xdrproc_t inproc, char *in, xdrproc_t outproc,
char *out);
5.1 – Arguments
host
A pointer to the name of the host on which the remote procedure
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.
5.2 – Description
Calls the remote procedure associated with prognum, versnum,
and procnum on the host host. This routine performs the same
functions as a set of calls to the clnt_create, clnt_call, and
clnt_destroy routines. This routine returns RPC_SUCCESS if it
succeeds, or the value of enum clnt_stat cast to an integer if it
fails. The routine clnt_perrno is handy for translating a failure
status into a message.
NOTE
Calling remote procedures with this routine uses UDP/IP as
a transport; see clntudp_create for restrictions. You do
not have control of timeouts or authentication using this
routine. If you want to use the TCP transport, use the clnt_
create or clnttcp_create routine.
5.3 – Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns a value of type enum clnt_stat cast to
type int containing the status of the callrpc
operation.
6 – clnt_broadcast
Executes a remote procedure call that is sent to all locally
connected networks using the broadcast address.
Format
#include <rpc/rpc.h>
enum clnt_stat clnt_broadcast(u_long prognum, u_long versnum,
u_long procnum, xdrproc_t inproc, char * in,
xdrproc_t outproc, char * out, resultproc_t
eachresult);
6.1 – Arguments
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.
eachresult
Called each time the routine receives a response. Specify the
routine as follows:
int eachresult(char *resultsp, struct sockaddr_in *addr)
resultsp is the same as the parameter passed to clnt_broadcast(),
except that the remote procedure's output is decoded there. addr
is a pointer to a sockaddr_in structure containing the address of
the host that sent the results.
If eachresult is NULL, the clnt_broadcast routine returns without
waiting for any replies.
6.2 – Description
Performs the same function as the callrpc routine, except that
the call message is sent to all locally connected networks using
the broadcast address. Each time it receives a response, this
routine calls the eachresult routine. If eachresult returns
zero, clnt_broadcast waits for more replies; otherwise it assumes
success and returns RPC_SUCCESS.
NOTE
This routine uses the UDP protocol. Broadcast sockets are
limited in size to the maximum transfer unit of the data
link. For Ethernet, this value is 1400 bytes. For FDDI, this
value is 4500 bytes.
6.3 – Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_broadcast
operation.
7 – clnt_call
A macro that calls a remote procedure.
Format
#include <rpc/rpc.h>
enum clnt_stat clnt_call(CLIENT *handle, u_long procnum,
xdrproc_t inproc, char *in, xdrproc_t outproc,
char *out, struct timeval timeout);
7.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
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 structure describing the time allowed for results to return to
the client. If you have previously used the clnt_control macro
with the CLSET_TIMEOUT code, this value is ignored.
7.2 – Description
Use the clnt_call macro after using one of the client-handle
creation routines. After you are finished with the handle, return
it using the clnt_destroy macro. Use the clnt_perror to print any
errors that occurred.
7.3 – Return Values
RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat
containing the status of the clnt_call
operation.
8 – clnt_control
A macro that changes or retrieves information about an RPC client
process.
Format
#include <rpc/rpc.h>
bool_t clnt_control(CLIENT *handle, u_int code, char *info);
8.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
code
A code designating the type of information to be set or
retrieved.
info
A pointer to a buffer containing the information for a SET
operation or the results of a GET operation.
8.2 – Description
For UDP and TCP transports specify any of the following for code:
CLSET_TIMEOUT struct Set total timeout
timeval
CLGET_TIMEOUT struct Get total timeout
timeval
CLGET_SERVER_ADDR struct Get server address
sockaddr_
in
CLGET_FD int Get associated socket
CL_FD_CLOSE void Close socket on clnt_destroy
CL_FD_NCLOSE void Leave socket open on clnt_
destroy
If you set the timeout using clnt_control, ONC RPC ignores the
timeout parameter in all future clnt_call calls. The default
total timeout is 25 seconds.
For the UDP transport two additional options are available:
CLSET_RETRY_ struct Set retry timeout
TIMEOUT timeval
CLGET_RETRY_ struct Get retry timeout
TIMEOUT timeval
The timeout value in these two calls is the time that UDP waits
for a response before retransmitting the message to the server.
The default time is 5 seconds. The retry timeout controls when
UDP retransmits the request; the total timeout controls the total
time that the client should wait for a response. For example,
with the default settings, UDP will retry the transmission four
times at 5-second intervals.
8.3 – Return Values
TRUE Success
FALSE Failure
9 – clnt_create_#
Creates a client handle and returns its address.
Format
#include <rpc/rpc.h>
CLIENT *clnt_create(char *host, u_long prognum, u_long
versnum, char *protocol);
9.1 – Arguments
host
A pointer to the name of the remote host.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
protocol
A pointer to a string containing the name of the protocol for
transmitting and receiving RPC messages. Specify either tcp or
udp.
9.2 – Description
The clnt_create routine creates an RPC client handle for prognum.
An RPC client handle is a structure containing information about
the RPC client. The client can use the UDP or TCP transport
protocol.
This routine uses the Portmapper. You cannot control the local
port.
The default sizes of the send and receive buffers are 8800 bytes
for the UDP transport, and 4000 bytes for the TCP transport. The
retry time for the UDP transport is five seconds.
Use the clnt_create routine instead of the callrpc or clnt_
broadcast routines if you want to use one of the following:
o The TCP transport
o A non-null authentication
o More than one active client at the same time
You can also use the clnttcp_create routine to use the TCP
protocol, or the clntudp_create routine to use the UDP protocol.
The clnt_create routine uses the global variable rpc_createerr.
rpc_createerr is a structure that contains the most recent
service creation error. Use rpc_createerrif you want the client
program to handle the error. The value of rpc_createerr is set by
any RPC client creation routine that does not succeed.
NOTE
If the requested program is available on the host but the
program does not support the requested version number, this
routine still succeeds. A subsequent call to the clnt_call
routine will discover the version mismatch. Use the clnt_
create_vers routine if you want to avoid this condition.
9.3 – Return Values
CLIENT * Client handle containing the server
information.
NULL Error occurred while creating the client
handle. Use the clnt_pcreateerror or clnt_
spcreateerror routine to obtain diagnostic
information.
10 – clnt_create_vers
Creates a client handle and returns its address. Seeks to use a
server supporting the highest version number within a specified
range.
Format
#include <rpc/rpc.h>
CLIENT *clnt_create_vers(char *host, u_long prognum, u_long
*versnum, u_long min_vers, u_long max_vers, char
*protocol);
10.1 – Arguments
host
A pointer to the name of the remote host.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure. This
value is returned by the routine. The value is the highest
version number supported by the remote server that is in the
range of version numbers specified by min_vers and max_vers. The
argument may remain undefined; see additional information in the
Description section.
min_vers
The minimum acceptable version number for the remote procedure.
max_vers
The maximum acceptable version number for the remote procedure.
protocol
A pointer to a string containing the name of the protocol for
transmitting and receiving RPC messages. Specify either tcp or
udp.
10.2 – Description
The clnt_create_vers routine creates an RPC client handle
for prognum. An RPC client handle is a structure containing
information about the RPC client. The client can use the UDP
or TCP transport protocol.
This routine uses the Portmapper. You cannot control the local
port.
The default sizes of the send and receive buffers are 8800 bytes
for the UDP transport, and 4000 bytes for the TCP transport. The
retry time for the UDP transport is 5 seconds.
The clnt_create_vers routine differs from the standard clnt_
create routine in that it seeks out the highest version number
supported by the server. If the server does not support any
version numbers within the requested range, the routine returns
NULL and the versnum variable is undefined.
The clnt_create_vers routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed.
10.3 – Return Values
CLIENT * Clien-thandle containing the server
information.
NULL Error occurred while creating the client
handle. Usually the error indicates that the
server does not support any version numbers
within the requested range. Use the clnt_
pcreateerror or clnt_spcreateerror routine to
obtain diagnostic information.
11 – clnt_destroy
A macro that frees the memory associated with an RPC client
handle.
Format
#include <rpc/rpc.h>
void clnt_destroy(CLIENT *handle);
11.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
11.2 – Description
The clnt_destroy routine destroys the client's RPC handle by
deallocating all memory related to the handle. The client is
undefined after the clnt_destroy call.
If the clnt_create routine had previously opened the socket
associated with the client handle or the program had used the
clnt_control routine to set CL_FD_CLOSE, this routine closes the
socket. If the clnt_create routine had not previously opened the
socket associated with the client handle or the program had used
the clnt_control routine to set CL_FD_NCLOSE, this routine leaves
the socket open.
11.3 – Return Values
None
12 – clnt_freeres
A macro that frees the memory that was allocated when the remote
procedure's results were decoded.
Format
#include <rpc/rpc.h>
bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char
*out);
12.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
outproc
The XDR routine used to decode the remote procedure's results.
out
A pointer to the remote procedure's results.
12.2 – Description
The clnt_freeres routine calls the xdr_free routine to deallocate
the memory where the remote procedure's results are stored.
12.3 – Return Values
TRUE Success.
FALSE Error occurred while freeing the memory.
13 – clnt_geterr
A macro that returns error information indicating why an RPC call
failed.
Format
#include <rpc/rpc.h>
void clnt_geterr(CLIENT *handle, struct rpc_err *errp);
13.1 – Arguments
handle
A pointer to a client handle created by any of the client-handle
creation routines.
errp
A pointer to an rpc_err structure containing information that
indicates why an RPC call failed. This information is the same
information as clnt_stat contains, plus one of the following:
the C error number, the range of server versions supported, or
authentication errors.
13.2 – Description
This macro copies the error information from the client handle
to the structure referenced by errp. The macro is mainly for
diagnostic use.
13.3 – Return Values
None
14 – clnt_pcreateerror
Prints a message explaining why ONC RPC could not create a client
handle.
Format
#include <rpc/rpc.h>
void clnt_pcreateerror(char *sp);
14.1 – Arguments
sp
A pointer to a string to be used as the beginning of the error
message.
14.2 – Description
The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The
message consists of the sp parameter followed by an RPC-generated
error message. Use this routine when the clnt_create, clnttcp_
create, or clntudp_create routine fails.
14.3 – Return Values
None
15 – clnt_perrno
Prints a message indicating why the callrpc or clnt_broadcast
routine failed.
Format
#include <rpc/rpc.h>
void clnt_perrno(enum clnt_stat stat) ;
15.1 – Arguments
stat
A buffer containing status information.
15.2 – Description
Prints a message to standard error corresponding to the condition
indicated by the stat argument.
The data type declaration for clnt_stat in rpc/rpc.h lists the
standard errors.
15.3 – Return Values
None
16 – clnt_perror
Prints a message explaining why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
void clnt_perror(CLIENT *handle, char *sp);
16.1 – Arguments
handle
A pointer to the client handle used in the call that failed.
sp
A pointer to a string to be used as the beginning of the error
message.
16.2 – Description
Prints a message to standard error indicating why an ONC RPC call
failed. The message is prepended with string sp and a colon.
16.3 – Return Values
None
17 – clnt_spcreateerror
Returns a message indicating why RPC could not create a client
handle.
Format
#include <rpc/rpc.h>
char *clnt_spcreateerror(char *sp);
17.1 – Arguments
sp
A pointer to a string to be used as the beginning of the error
message.
17.2 – Description
The clnt_spcreateerror routine returns the address of a message
string. The message consists of the sp parameter followed by an
error message generated by calling the clnt_sperrno routine. Use
the clnt_spcreateerror routine when the clnt_create, clnttcp_
create, or clntudp_create routine fails.
Use this routine if:
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.
The address that clnt_spcreateerror returns is the address of
its own internal string buffer. The clnt_spcreateerror routine
overwrites this buffer with each call. Therefore, you must copy
the string to your own buffer if you wish to save the string.
17.3 – Return Values
char * A pointer to the message string terminated
with a NULL character.
NULL The routine was not able to allocate its
internal buffer.
18 – clnt_sperrno
Returns a message indicating why the callrpc or clnt_broadcast
routine failed to create a client handle.
Format
#include <rpc/rpc.h>
char *clnt_sperrno(enum clnt_stat stat);
18.1 – Arguments
stat
A buffer containing status information.
18.2 – Description
The clnt_sperrno routine returns a pointer to a string.
Use this routine instead if:
o The server does not have a stderr file; many servers do not.
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.
The address that clnt_sperrno returns is a pointer to the error
message string for the error. Therefore, you do not have to copy
the string to your own buffer in order to save the string.
18.3 – Return Values
char * A pointer to the message string terminated
with a NULL character.
19 – clnt_sperror
Returns a message indicating why an ONC RPC routine failed.
Format
#include <rpc/rpc.h>
char *clnt_sperror(CLIENT *handle, char *sp);
19.1 – Arguments
handle
A pointer to the client handle used in the call that failed.
sp
A pointer to a string to be used as the beginning of the error
message.
19.2 – Description
The clnt_sperror routine returns a pointer to a message string.
The message consists of the sp parameter followed by an error
message generated by calling the clnt_sperrno routine. Use this
routine when the clnt_call routine fails.
Use this routine if:
o You want to save the string.
o You do not want to use fprintf to print the message.
o The message format is different from the one that clnt_perrno
supports.
The address that clnt_sperror returns is a pointer to its own
internal string buffer. The clnt_sperror routine overwrites this
buffer with each call. Therefore, you must copy the string to
your own buffer if you wish to save the string.
19.3 – Return Values
char * A pointer to the message string terminated
with a NULL character.
NULL The routine was not able to allocate its
internal buffer.
20 – clntraw_create
Creates a client handle for memory-based ONC RPC for simple
testing and timing.
Format
#include <rpc/rpc.h>
CLIENT *clntraw_create(u_long prognum, u_long versnum);
20.1 – Arguments
prognum
The program number associated with the remote program.
versnum
The version number associated with the remote program.
20.2 – Description
Creates an in-program ONC 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 server should live in the same
address space; see svcraw_create. This allows simulation of
and acquisition of ONC RPC overheads, such as round-trip times,
without any kernel interference.
20.3 – Return Values
CLIENT * A pointer to a client handle.
NULL Indicates failure.
21 – clnttcp_create
Creates an ONC RPC client handle for a TCP/IP connection.
Format
#include <rpc/rpc.h>
CLIENT *clnttcp_create(struct sockaddr_in *addr, u_long
prognum, u_long versnum, int *sockp, u_int sendsize,
u_int recvsize);
21.1 – Arguments
addr
A pointer to a buffer containing the Internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
21.2 – Description
Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses TCP/IP as a
transport. The routine is similar to the clnt_create routine,
except clnttcp_create allows you to specify a socket and the send
and receive buffer sizes.
If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.
The clnttcp_create routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.
The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.
NOTE
If the requested program is available on the host but the
program does not support the requested version number, this
routine still succeeds. A subsequent call to the clnt_call
routine will discover the version mismatch. Use the clnt_
create_vers routine if you want to avoid this condition.
21.3 – Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
22 – clntudp_bufcreate
Creates an ONC RPC client handle for a buffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, u_long
prognum, u_long versnum, struct timeval wait, register
int *sockp, u_int sendsize, u_int recvsize);
22.1 – Arguments
addr
A pointer to a buffer containing the Internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
wait
The amount of time used between call retransmission if no
response is received. Retransmission occurs until the ONC RPC
calls time out.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
sendsize
The size of the send buffer. If you specify zero, the routine
chooses a suitable default.
recvsize
The size of the receive buffer. If you specify zero, the routine
chooses a suitable default.
22.2 – Description
Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses UDP as the
transport. The routine is similar to the clnt_create routine,
except clntudp_bufcreate allows you to specify a socket, the UDP
retransmission time, and the send and receive buffer sizes.
If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.
The clntudp_bufcreate routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.
The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.
NOTE
If addr->sin_port is 0 and the requested program is
available on the host but the program does not support the
requested version number, this routine still succeeds. A
subsequent call to the clnt_call routine will discover the
version mismatch. Use the clnt_create_vers routine if you
want to avoid this condition.
22.3 – Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
23 – clntudp_create
Creates an ONC RPC client handle for a nonbuffered I/O UDP
connection.
Format
#include <rpc/rpc.h>
CLIENT *clntudp_create(struct sockaddr_in *addr, u_long
prognum, u_long versnum, struct timeval wait, register
int *sockp);
23.1 – Arguments
addr
A pointer to a buffer containing the Internet address where the
remote program is located.
prognum
The program number associated with the remote procedure.
versnum
The version number associated with the remote procedure.
wait
The amount of time used between call retransmission if no
response is received. Retransmission occurs until the ONC RPC
calls time out.
sockp
A pointer to the socket number to be used for the remote
procedure call. If sockp is RPC_ANYSOCK, then this routine opens
a new socket and sets sockp.
23.2 – Description
Creates an ONC RPC client handle for the remote program prognum,
version versnum at address addr. The client uses UDP as the
transport. The routine is similar to the clnt_create routine,
except clntudp_create allows you to specify a socket and the UDP
retransmission time.
If you specify the port number as zero by using addr->sin_port,
the Portmapper provides the number of the port on which the
remote program is listening.
The clntudp_create routine uses the global variable rpc_
createerr. rpc_createerr is a structure that contains the most
recent service creation error. Use rpc_createerr if you want the
client program to handle the error. The value of rpc_createerr is
set by any RPC client creation routine that does not succeed. The
rpc_createerr variable is defined in the CLNT.H file.
The socket referenced by sockp is copied into a private area for
RPC to use. It is the client's responsibility to close the socket
referenced by sockp.
The authentication scheme for the client, client->cl_auth, gets
set to null authentication. The calling program can set this to
something different if necessary.
NOTES
Since UDP/IP messages can only hold up to 8 KB of encoded
data, this transport cannot be used for procedures that take
large arguments or return huge results.
If addr->sin_port is 0 and the requested program is
available on the host but the program does not support the
requested version number, this routine still succeeds. A
subsequent call to the clnt_call routine will discover the
version mismatch. Use the clnt_create_vers routine if you
want to avoid this condition.
23.3 – Return Values
CLIENT * A pointer to the client handle.
NULL Indicates failure.
24 – get_myaddress
Returns the local host's Internet address.
Format
#include <rpc/rpc.h>
void get_myaddress(struct sockaddr_in *addr);
24.1 – Arguments
addr
A pointer to a sockaddr_in structure that the routine will load
with the Internet address of the host where the local procedure
resides.
24.2 – Description
Puts the local host's Internet address into addr without doing
any name translation. The port number is always set to htons
(PMAPPORT).
24.3 – Return Values
None
25 – get_myaddr_dest
Returns the local host's Internet address according to a
destination address.
Format
#include <rpc/rpc.h>
void get_myaddr_dest(struct sockaddr_in *addr, struct
sockaddr_in *dest);
25.1 – Arguments
addr
A pointer to a sockaddr_in structure that the routine will load
with the local Internet address that would provide a connection
to the remote address specified in dest.
dest
A pointer to a sockaddr_in structure containing an Internet
address of a remote host.
25.2 – Description
Since the local host may have multiple network addresses (each
on its own interface), this routine is used to select the local
address that would provide a connection to the remote address
specified in dest.
This is an alternative to gethostbyname, which invokes yellow
pages. It takes a destination (where we are trying to get to) and
finds an exact network match to go to.
25.3 – Return Values
None