svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
rpc_soc(3c)
rpc_soc(3C) Standard C Library Functions rpc_soc(3C)
NAME
rpc_soc, authdes_create, authunix_create, authunix_create_default,
callrpc, clnt_broadcast, clntraw_create, clnttcp_create,
clntudp_bufcreate, clntudp_create, get_myaddress, getrpcport,
pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, pmap_unset, regis‐
terrpc, svc_fds, svc_getcaller, svc_getreq, svc_register, svc_unregis‐
ter, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate,
svcudp_create, xdr_authunix_parms - obsolete library routines for RPC
SYNOPSIS
#define PORTMAP
#include <rpc/rpc.h>
AUTH *authdes_create(char *name, uint_t window,
struct sockaddr_in *syncaddr, des_block *ckey);
AUTH *authunix_create(char *host, uid_t uid, gid_t gid,
int grouplen, gid_t *gidlistp);
AUTH *authunix_create_default(void)
int callrpc(char *host, rpcprog_t prognum, rpcvers_t versnum,
rpcproc_t procnum, xdrproc_t inproc, char *in,
xdrproc_t outproc, char *out);
enum clnt_stat_clnt_broadcast(rpcprog_t prognum, rpcvers_t versnum,
rpcproc_t procnum, xdrproc_t inproc, char *in,
xdrproc_t outproc, char *out, resultproc_t eachresult);
CLIENT *clntraw_create(rpcproc_t procnum, rpcvers_t versnum);
CLIENT *clnttcp_create(struct sockaddr_in *addr,
rpcprog_t prognum, rpcvers_t versnum, int *fdp,
uint_t sendz, uint_t recvsz);
CLIENT *clntudp_bufcreate(struct sockaddr_in *addr, rpcprog_t prognum,
rpcvers_t versnum, struct timeval wait,
int *fdp, uint_t sendz, uint_t recvsz);
CLIENT *clntudp_create(struct sockaddr_in *addr, rpcprog_t prognum,
rpcvers_t versnum, struct timeval wait, int *fdp);
void get_myaddress(struct sockaddr_in *addr);
ushort getrpcport(char *host, rpcprog_t prognum,
rpcvers_t versnum, rpcprot_t proto);
struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);
ushort pmap_getport(struct sockaddr_in *addr,
rpcprog_t prognum, rpcvers_t versnum,
rpcprot_t protocol);
enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr,
rpcprog_t prognum, rpcvers_t versnum,
rpcproc_t progcnum, caddr_t in, xdrproct_t inproc,
caddr_t out, cdrproct_t outproc,
struct timeval tout, rpcport_t *portp);
bool_t pmap_set(rpcprog_t prognum, rpcvers_t versnum,
rpcprot_t protocol, u_short port);
bool_t pmap_unset(rpcprog_t prognum, rpcvers_t versnum);
int svc_fds;
struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);
void svc_getreq(int rdfds);
SVCXPRT *svcfd_create(int fd, uint_t sendsz,
uint_t recvsz);
SVCXPRT *svcraw_create(void)
SVCXPRT *svctcp_create(int fd, uint_t sendsz,
uint_t recvsz);
SVCXPRT *svcudp_bufcreate(int fd, uint_t sendsz,
uint_t recvsz);
SVCXPRT *svcudp_create(int fd);
int registerrpc(rpcprog_t prognum, rpcvers_t versnum, rpcproc_t procnum,
char *(*procname)(), xdrproc_t inproc, xdrproc_t outproc);
bool_tsvc_register(SVCXPRT *xprt, rpcprog_t prognum, rpcvers_t versnum,
void (*dispatch(), int protocol);
void svc_unregister(rpcprog_t prognum, rpcvers_t versnum);
bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *supp);
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 re‐
quest 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.
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.
File Descriptors
Transport independent RPC uses TLI as its transport interface instead
of sockets.
Some of the routines described in this section (such as clnttcp_cre‐
ate()) take a pointer to a file descriptor as one of the parameters. If
the user wants the file descriptor to be a socket, then the application
will have to be linked with both librpcsoc and libnsl. If the user
passed RPC_ANYSOCK as the file descriptor, and the application is
linked with libnsl only, then the routine will return a TLI file de‐
scriptor and not a socket.
Routines
The following routines require that the header <rpc/rpc.h> be included.
The symbol PORTMAP should be defined so that the appropriate function
declarations for the old interfaces are included through the header
files.
authdes_create() authdes_create() is the first of two rou‐
tines which interface to the RPC secure au‐
thentication system, known as DES authenti‐
cation. The second is authdes_getucred(),
below. Note: the keyserver daemon key‐
serv(8) must be running for the DES authen‐
tication system to work.
authdes_create(), 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 rep‐
resents a hostname derived from the utility
routine host2netname(), but could also rep‐
resent a user name using user2netname().
See secure_rpc(3C). The second field is
window on the validity of the client cre‐
dential, given in seconds. A small window
is more secure than a large one, but choos‐
ing 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 au‐
thentication system will assume that the
local clock is always in sync with the
server's clock, and will not attempt resyn‐
chronizations. If an address is supplied,
however, then the system will use the ad‐
dress for consulting the remote time ser‐
vice whenever resynchronization is re‐
quired. This parameter is usually the ad‐
dress of the RPC server itself. The final
parameter ckey is also optional. If it is
NULL, then the authentication 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 in‐
stead.
This routine exists for backward compati‐
bility only, and it is made obsolete by au‐
thdes_seccreate(). See secure_rpc(3C).
authunix_create() Create and return an RPC authentication
handle that contains UNIX 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.
It is not very difficult to impersonate a
user.
This routine exists for backward compati‐
bility only, and it is made obsolete by
authsys_create(). See rpc_clnt_auth(3C).
authunix_create_default() Call authunix_create() with the appropriate
parameters.
This routine exists for backward compati‐
bility only, and it is made obsolete by
authsys_create_default(). See
rpc_clnt_auth(3C).
callrpc() Call the remote procedure associated with
prognum, versnum, and procnum on the ma‐
chine, 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 proce‐
dure's argument, and out is the address of
where to place the result(s). This routine
returns 0 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 failure statuses into mes‐
sages. See rpc_clnt_calls(3C).
You do not have control of timeouts or au‐
thentication using this routine. This rou‐
tine exists for backward compatibility
only, and is made obsolete by rpc_call().
See rpc_clnt_calls(3C).
clnt_stat_clnt_broadcast() Like callrpc(), except the call message is
broadcast to all locally connected broad‐
cast nets. Each time the caller receives a
response, this routine calls eachresult,
whose form is:
eachresult(char *out, struct sockaddr_in *addr);
where out is the same as out passed to
clnt_broadcast(), except that the remote
procedure's output is decoded there; addr
points to the address of the machine that
sent the results. If eachresult returns 0,
clnt_broadcast() waits for more replies;
otherwise it returns with appropriate sta‐
tus. If eachresult is NULL, clnt_broad‐
cast() returns without waiting for any
replies.
Broadcast packets are limited in size to
the maximum transfer unit of the transports
involved. For Ethernet, the caller's argu‐
ment size is approximately 1500 bytes.
Since the call message is sent to all con‐
nected networks, it may potentially lead to
broadcast storms. clnt_broadcast() uses
AUTH_SYS credentials by default. See
rpc_clnt_auth(3C). This routine exists for
backward compatibility only, and is made
obsolete by rpc_broadcast(). See
rpc_clnt_calls(3C).
clntraw_create() 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 ac‐
tually a buffer within the process's ad‐
dress space, so the corresponding RPC
server should live in the same address
space. See svcraw_create(). This allows
simulation of RPC and acquisition of RPC
overheads, such as round trip times, with‐
out any kernel interference. This routine
returns NULL if it fails.
This routine exists for backward compati‐
bility only. It has the same functionality
as clnt_raw_create(). See rpc_clnt_cre‐
ate(3C), which obsoletes it.
clnttcp_create() 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 ad‐
dress addr. If addr->sin_port is 0, then it
is set to the actual port that the remote
program is listening on. The remote rpcbind
service is consulted for this information.
The parameter *fdp is a file descriptor,
which may be open and bound; if it is
RPC_ANYSOCK, then this routine opens a new
one and sets *fdp. Refer to the File De‐
scriptor 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 0 choose suitable de‐
faults. This routine returns NULL if it
fails.
This routine exists for backward compati‐
bility only. clnt_create(), clnt_tli_cre‐
ate(), or clnt_vc_create() should be used
instead. See rpc_clnt_create(3C).
clntudp_bufcreate() Create a client handle for the remote pro‐
gram prognum, version versnum; the client
uses UDP/IP as the transport. The remote
program is located at the Internet address
addr. If addr->sin_port is 0, it is set to
the actual port that the remote program is
listening on (the remote rpcbind service is
consulted for this information). The para‐
meter *fdp is a file descriptor, which may
be open and bound. If it is RPC_ANYSOCK,
then this routine opens a new one and sets
*fdp. Refer to the File Descriptor section
for more information. The UDP transport re‐
sends 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
clnt_call(). See rpc_clnt_calls(3C). If
successful it returns a client handle, oth‐
erwise it returns NULL. The error can be
printed using the clnt_pcreateerror() rou‐
tine. See rpc_clnt_create(3C).
The user can specify the maximum packet
size for sending and receiving by using
sendsz and recvsz arguments for UDP-based
RPC messages.
If addr->sin_port is 0 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
clnt_call() later (see rpc_clnt_calls(3C)).
This routine exists for backward compati‐
bility only. clnt_tli_create() or
clnt_dg_create() should be used instead.
See rpc_clnt_create(3C).
clntudp_create() This routine creates an RPC client handle
for the remote program prognum, version
versnum; the client uses UDP/IP as a trans‐
port. The remote program is located at In‐
ternet address addr. If addr->sin_port is
0, then it is set to the actual port that
the remote program is listening on. The re‐
mote rpcbind service is consulted for this
information. The parameter *fdp is a file
descriptor, which may be open and bound; if
it is RPC_ANYSOCK, then this routine opens
a new one and sets *fdp. Refer to the File
Descriptor 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 clnt_call(). See
rpc_clnt_calls(3C). clntudp_create() re‐
turns a client handle on success, otherwise
it returns NULL. The error can be printed
using the clnt_pcreateerror() routine. See
rpc_clnt_create(3C).
Since UDP-based RPC messages can only hold
up to 8 Kbytes of encoded data, this trans‐
port cannot be used for procedures that
take large arguments or return huge re‐
sults.
This routine exists for backward compati‐
bility only. clnt_create(), clnt_tli_cre‐
ate(), or clnt_dg_create() should be used
instead. See rpc_clnt_create(3C).
get_myaddress() Places the local system's IP address into
*addr, without consulting the library rou‐
tines that deal with the hosts(5) database.
The port number is always set to
htons(PMAPPORT).
This routine is only intended for use with
the RPC library. It returns the local sys‐
tem'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 actu‐
ally zeroed. This address may have only lo‐
cal 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.
This routine remains for backward compati‐
bility only. The routine netdir_getbyname()
should be used with the name HOST_SELF to
retrieve the local system's network address
as a netbuf structure. See netdir(3C).
getrpcport() getrpcport() returns the port number for
the version versnum of the RPC program
prognum running on host and using protocol
proto. getrpcport() returns 0 if the RPC
system failed to contact the remote portmap
service, the program associated with
prognum is not registered, or there is no
mapping between the program and a port.
This routine exists for backward compati‐
bility only. Enhanced functionality is pro‐
vided by rpcb_getaddr(). See rpcbind(3C).
pmaplist() A user interface to the portmap service,
which returns a list of the current RPC
program-to-port mappings on the host lo‐
cated at IP address addr. This routine can
return NULL. The command 'rpcinfo -p' uses
this routine.
This routine exists for backward compati‐
bility only, enhanced functionality is pro‐
vided by rpcb_getmaps(). See rpcbind(3C).
pmap_getport() A user interface to the portmap 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
IPPROTO_UDP or IPPROTO_TCP. A return value
of 0 means that the mapping does not exist
or that the RPC system failed to contact
the remote portmap service. In the latter
case, the global variable rpc_createerr
contains the RPC status.
This routine exists for backward compati‐
bility only, enhanced functionality is pro‐
vided by rpcb_getaddr(). See rpcbind(3C).
pmap_rmtcall() Request that the portmap on the host at IP
address *addr make an RPC on the behalf of
the caller to a procedure on that host.
*portp is modified to the program's port
number if the procedure succeeds. The defi‐
nitions of other parameters are discussed
in callrpc() and clnt_call(). See
rpc_clnt_calls(3C).
This procedure is only available for the
UDP transport.
If the requested remote procedure is not
registered with the remote portmap then no
error response is returned and the call
times out. Also, no authentication is done.
This routine exists for backward compati‐
bility only, enhanced functionality is pro‐
vided by rpcb_rmtcall(). See rpcbind(3C).
pmap_set() A user interface to the portmap service,
that establishes a mapping between the
triple [prognum, versnum, protocol] and
port on the machine's portmap service. The
value of protocol may be IPPROTO_UDP or IP‐
PROTO_TCP. 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 1 if it
succeeds, 0 otherwise. Automatically done
by svc_register().
This routine exists for backward compati‐
bility only, enhanced functionality is pro‐
vided by rpcb_set(). See rpcbind(3C).
pmap_unset() A user interface to the portmap service,
which destroys all mapping between the
triple [prognum, versnum, all-protocols]
and port on the machine's portmap service.
This routine returns one if it succeeds, 0
otherwise.
This routine exists for backward compati‐
bility only, enhanced functionality is pro‐
vided by rpcb_unset(). See rpcbind(3C).
svc_fds() A global variable reflecting the RPC ser‐
vice side's read file descriptor bit mask;
it is suitable as a parameter to the se‐
lect() call. This is only of interest if a
service implementor does not call
svc_run(), but rather does their own asyn‐
chronous event processing. This variable is
read-only, yet it may change after calls to
svc_getreq() or any creation routines. Do
not pass its address to select()! Similar
to svc_fdset, but limited to 32 descrip‐
tors.
This interface is made obsolete by svc_fd‐
set. See rpc_svc_calls(3C).
svc_getcaller() This routine returns the network address,
represented as a struct sockaddr_in, of the
caller of a procedure associated with the
RPC service transport handle, xprt.
This routine exists for backward compati‐
bility only, and is obsolete. The preferred
interface is svc_getrpccaller(). See
rpc_svc_reg(3C), which returns the address
as a struct netbuf.
svc_getreq() This routine is only of interest if a ser‐
vice implementor does not call svc_run(),
but instead implements custom asynchronous
event processing. It is called when the se‐
lect() call has determined that an RPC re‐
quest has arrived on some RPC file descrip‐
tors; rdfds is the resultant read file de‐
scriptor bit mask. The routine returns when
all file descriptors associated with the
value of rdfds have been serviced. This
routine is similar to svc_getreqset() but
is limited to 32 descriptors.
This interface is made obsolete by svc_ge‐
treqset()
svcfd_create() Create a service on top of any open and
bound descriptor. Typically, this descrip‐
tor is a connected file descriptor for a
stream protocol. Refer to the File Descrip‐
tor section for more information. sendsz
and recvsz indicate sizes for the send and
receive buffers. If they are 0, a reason‐
able default is chosen.
This interface is made obsolete by
svc_fd_create() (see rpc_svc_create(3C)).
svcraw_create() 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's address
space, so the corresponding RPC client
should live in the same address space; see
clntraw_create(). This routine allows simu‐
lation of RPC and acquisition of RPC over‐
heads (such as round trip times), without
any kernel interference. This routine re‐
turns NULL if it fails.
This routine exists for backward compati‐
bility only, and has the same functionality
of svc_raw_create(). See rpc_svc_cre‐
ate(3C), which obsoletes it.
svctcp_create() 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
RPC_ANYSOCK, in which case a new file de‐
scriptor is created. If the file descriptor
is not bound to a local TCP port, then this
routine binds it to an arbitrary port. Re‐
fer to the File Descriptor section for more
information. Upon completion, xprt->xp_fd
is the transport's file descriptor, and
xprt->xp_port is the transport's port num‐
ber. This routine returns NULL if it fails.
Since TCP-based RPC uses buffered I/O,
users may specify the size of buffers; val‐
ues of 0 choose suitable defaults.
This routine exists for backward compati‐
bility only. svc_create(), svc_tli_cre‐
ate(), or svc_vc_create() should be used
instead. See rpc_svc_create(3C).
svcudp_bufcreate() 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
RPC_ANYSOCK then a new file descriptor is
created. If the file descriptor is not
bound to a local UDP port, then this rou‐
tine binds it to an arbitrary port. Upon
completion, xprtxp_fd is the transport's
file descriptor, and xprt->xp_port is the
transport's port number. Refer to the File
Descriptor section 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 pa‐
rameters.
This routine exists for backward compati‐
bility only. svc_tli_create(), or
svc_dg_create() should be used instead. See
rpc_svc_create(3C).
svcudp_create() 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
RPC_ANYSOCK, in which case a new file de‐
scriptor 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, xprt->xp_fd is the transport's
file descriptor, and xprt->xp_port is the
transport's port number. This routine re‐
turns NULL if it fails.
Since UDP-based RPC messages can only hold
up to 8 Kbytes of encoded data, this trans‐
port cannot be used for procedures that
take large arguments or return huge re‐
sults.
This routine exists for backward compati‐
bility only. svc_create(), svc_tli_cre‐
ate(), or svc_dg_create() should be used
instead. See rpc_svc_create(3C).
registerrpc() Register program prognum, procedure proc‐
name, and version versnum with the RPC ser‐
vice package. If a request arrives for pro‐
gram prognum, version versnum, and proce‐
dure procnum, procname is called with a
pointer to its parameter(s). procname
should return a pointer to its static re‐
sult(s). inproc is used to decode the para‐
meters while outproc is used to encode the
results. This routine returns 0 if the reg‐
istration succeeded, −1 otherwise.
svc_run() must be called after all the ser‐
vices are registered.
This routine exists for backward compati‐
bility only, and it is made obsolete by
rpc_reg().
svc_register() Associates prognum and versnum with the
service dispatch procedure, dispatch. If
protocol is 0, the service is not regis‐
tered with the portmap service. If protocol
is non-zero, then a mapping of the triple
[prognum, versnum, protocol] to
xprt->xp_port is established with the local
portmap service (generally protocol is 0,
IPPROTO_UDP or IPPROTO_TCP). The procedure
dispatch has the following form:
dispatch(struct svc_req *request, SVCXPRT *xprt);
The svc_register() routine returns one if
it succeeds, and 0 otherwise.
This routine exists for backward compati‐
bility only. Enhanced functionality is pro‐
vided by svc_reg().
svc_unregister() Remove all mapping of the double [prognum,
versnum] to dispatch routines, and of the
triple [prognum, versnum, all-protocols] to
port number from portmap.
This routine exists for backward compati‐
bility. Enhanced functionality is provided
by svc_unreg().
xdr_authunix_parms() Used for describing UNIX credentials. This
routine is useful for users who wish to
generate these credentials without using
the RPC authentication package.
This routine exists for backward compati‐
bility only, and is made obsolete by
xdr_authsys_parms(). See rpc_xdr(3C).
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityObsolete _ MT-LevelUnsafe
SEE ALSO
netdir(3C), netdir_getbyname(3C), rpc(3C), rpc_clnt_auth(3C),
rpc_clnt_calls(3C), rpc_clnt_create(3C), rpc_svc_calls(3C),
rpc_svc_create(3C), rpc_svc_err(3C), rpc_svc_reg(3C), rpc_xdr(3C),
rpcbind(3C), secure_rpc(3C), select(3C), xdr_authsys_parms(3C), lib‐
nsl(3LIB), attributes(7), keyserv(8), rpcbind(8), rpcinfo(8)
NOTES
These interfaces are unsafe in multithreaded applications. Unsafe in‐
terfaces should be called only from the main thread.
Oracle Solaris 11.4 6 Oct 2022 rpc_soc(3C)