path: root/usr/src/man/man3nsl/rpc_soc.3nsl

'\" te
.\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
.\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH RPC_SOC 3NSL "May 22, 2022"
.SH 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, registerrpc, 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
.SH SYNOPSIS
.nf
#define PORTMAP
#include <rpc/rpc.h>
.fi

.LP
.nf
\fBAUTH *\fR\fBauthdes_create\fR(\fBchar *\fR\fIname\fR, \fBuint_t\fR \fIwindow\fR,
     \fBstruct sockaddr_in *\fR\fIsyncaddr\fR, \fBdes_block *\fR\fIckey\fR,
     \fBint\fR \fIcalltype\fR, \fBAUTH **\fR\fIretauth\fR);
.fi

.LP
.nf
\fBAUTH *\fR\fBauthunix_create\fR(\fBchar *\fR\fIhost\fR, \fBuid_t\fR \fIuid\fR, \fBgid_t\fR \fIgid\fR,
     \fBint\fR \fIgrouplen\fR, \fBgid_t *\fR\fIgidlistp\fR);
.fi

.LP
.nf
\fBAUTH *\fR\fBauthunix_create_default\fR(void)
.fi

.LP
.nf
\fBint\fR \fBcallrpc\fR(\fBchar *\fR\fIhost\fR, \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
     \fBrpcproc_t\fR \fIprocnum\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBchar *\fR\fIin\fR,
     \fBxdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR);
.fi

.LP
.nf
\fBenum\fR \fBclnt_stat_clnt_broadcast\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
     \fBrpcproc_t\fR \fIprocnum\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBchar *\fR\fIin\fR,
     \fBxdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR, \fBresultproc_t\fR \fIeachresult\fR);
.fi

.LP
.nf
\fBCLIENT *\fR\fBclntraw_create\fR(\fBrpcproc_t\fR \fIprocnum\fR, \fBrpcvers_t\fR \fIversnum\fR);
.fi

.LP
.nf
\fBCLIENT *\fR\fBclnttcp_create\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
     \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, \fBint *\fR\fIfdp\fR,
     \fBuint_t\fR \fIsendz\fR, \fBuint_t\fR \fIrecvsz\fR);
.fi

.LP
.nf
\fBCLIENT *\fR\fBclntudp_bufcreate\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, \fBrpcprog_t\fR \fIprognum\fR,
     \fBrpcvers_t\fR \fIversnum\fR, \fBstruct timeval\fR \fIwait\fR,
     \fBint *\fR\fIfdp\fR, \fBuint_t\fR \fIsendz\fR, \fBuint_t\fR \fIrecvsz\fR);
.fi

.LP
.nf
\fBCLIENT *\fR\fBclntudp_create\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, \fBrpcprog_t\fR \fIprognum\fR,
     \fBrpcvers_t\fR \fIversnum\fR, \fBstruct timeval\fR \fIwait\fR, \fBint *\fR\fIfdp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBget_myaddress\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR);
.fi

.LP
.nf
\fBushort\fR \fBgetrpcport\fR(\fBchar *\fR\fIhost\fR, \fBrpcprog_t\fR \fIprognum\fR,
     \fBrpcvers_t\fR \fIversnum\fR, \fBrpcprot_t\fR \fIproto\fR);
.fi

.LP
.nf
\fBstruct pmaplist *\fR\fBpmap_getmaps\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR);
.fi

.LP
.nf
\fBushort\fR \fBpmap_getport\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
     \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
     \fBrpcprot_t\fR \fIprotocol\fR);
.fi

.LP
.nf
\fBenum clnt_stat\fR \fBpmap_rmtcall\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
     \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
     \fBrpcproc_t\fR \fIprogcnum\fR, \fBcaddr_t\fR \fIin\fR, \fBxdrproct_t\fR \fIinproc\fR,
     \fBcaddr_t\fR \fIout\fR, \fBcdrproct_t\fR \fIoutproc\fR,
     \fBstruct timeval\fR \fItout\fR, \fBrpcport_t *\fR\fIportp\fR);
.fi

.LP
.nf
\fBbool_t\fR \fBpmap_set\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
     \fBrpcprot_t\fR \fIprotocol\fR, \fBu_short\fR \fIport\fR);
.fi

.LP
.nf
\fBbool_t\fR \fBpmap_unset\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR);
.fi

.LP
.nf
int svc_fds;
.fi

.LP
.nf
\fBstruct sockaddr_in *\fR\fBsvc_getcaller\fR(\fBSVCXPRT *\fR\fIxprt\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsvc_getreq\fR(\fBint\fR \fIrdfds\fR);
.fi

.LP
.nf
\fBSVCXPRT *\fR\fBsvcfd_create\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR,
     \fBuint_t\fR \fIrecvsz\fR);
.fi

.LP
.nf
\fBSVCXPRT *\fR\fBsvcraw_create\fR(void)
.fi

.LP
.nf
\fBSVCXPRT *\fR\fBsvctcp_create\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR,
     \fBuint_t\fR \fIrecvsz\fR);
.fi

.LP
.nf
\fBSVCXPRT *\fR\fBsvcudp_bufcreate\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR,
     \fBuint_t\fR \fIrecvsz\fR);
.fi

.LP
.nf
\fBSVCXPRT *\fR\fBsvcudp_create\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBint\fR \fBregisterrpc\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, \fBrpcproc_t\fR \fIprocnum\fR,
     \fBchar *(*procname)()\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBxdrproc_t\fR \fIoutproc\fR);
.fi

.LP
.nf
\fBbool_t\fR \fBsvc_register\fR(\fBSVCXPRT *\fR\fIxprt\fR, \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
     \fBvoid (*)\fR\fIdispatch()\fR, \fBint\fR \fIprotocol\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsvc_unregister\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR);
.fi

.LP
.nf
\fBbool_t\fR \fBxdr_authunix_parms\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct authunix_parms *\fR\fIsupp\fR);
.fi

.SH DESCRIPTION
\fBRPC\fR 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.
.sp
.LP
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.
.SS "File Descriptors"
Transport independent \fBRPC\fR uses \fBTLI\fR as its transport interface
instead of sockets.
.sp
.LP
Some of the routines described in this section (such as \fBclnttcp_create()\fR)
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 \fBlibrpcsoc\fR and \fBlibnsl\fR. If the user passed
\fBRPC_ANYSOCK\fR as the file descriptor, and the application is linked with
\fBlibnsl\fR only, then the routine will return a \fBTLI\fR file descriptor
and not a socket.
.SS "Routines"
The following routines require that the header \fB<rpc/rpc.h>\fR be included.
The symbol \fBPORTMAP\fR should be defined so that the appropriate function
declarations for the old interfaces are included through the header files.
.sp
.ne 2
.na
\fB\fBauthdes_create()\fR\fR
.ad
.RS 30n
\fBauthdes_create()\fR is the first of two routines which interface to the
\fBRPC\fR secure authentication system, known as \fBDES\fR authentication. The
second is \fBauthdes_getucred()\fR, see \fBsecure_rpc\fR(3NSL).  Note: the
keyserver daemon \fBkeyserv\fR(8) must be running for the \fBDES\fR
authentication system to work.
.sp
\fBauthdes_create()\fR, used on the client side, returns an authentication
handle that will enable the use of the secure authentication system. The first
parameter \fIname\fR is the network name, or \fInetname\fR, of the owner of the
server process.  This field usually represents a hostname derived from the
utility routine \fBhost2netname()\fR, but could also represent a user name
using \fBuser2netname()\fR. See \fBsecure_rpc\fR(3NSL). The second field is
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 \fIsyncaddr\fR is optional.  If it is \fBNULL\fR, 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
usually the address of the \fBRPC\fR server itself. The final parameter
\fIckey\fR is also optional. If it is \fBNULL\fR, then the authentication
system will generate a random \fBDES\fR key to be used for the encryption of
credentials. If it is supplied, however, then it will be used instead.
.sp
This routine exists for backward compatibility only, and it is made obsolete by
\fBauthdes_seccreate()\fR. See \fBsecure_rpc\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBauthunix_create()\fR\fR
.ad
.RS 30n
Create and return an \fBRPC\fR authentication handle that contains UNIX
authentication information. The parameter \fIhost\fR is the name of the machine
on which the information was created; \fIuid\fR is the user's user \fBID\fR;
\fIgid\fR is the user's current group \fBID\fR; \fIgrouplen\fR and
\fIgidlistp\fR refer to a counted array of groups to which the user belongs.
.sp
It is not very difficult to impersonate a user.
.sp
This routine exists for backward compatibility only, and it is made obsolete by
\fBauthsys_create()\fR. See \fBrpc_clnt_auth\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBauthunix_create_default()\fR\fR
.ad
.RS 30n
Call \fBauthunix_create()\fR with the appropriate parameters.
.sp
This routine exists for backward compatibility only, and it is made obsolete by
\fBauthsys_create_default()\fR. See \fBrpc_clnt_auth\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBcallrpc()\fR\fR
.ad
.RS 30n
Call the remote procedure associated with \fIprognum\fR, \fIversnum\fR, and
\fIprocnum\fR on the machine, \fIhost\fR. The parameter \fIinproc\fR is used to
encode the procedure's parameters, and \fIoutproc\fR is used to decode the
procedure's results; \fIin\fR is the address of the procedure's argument, and
\fIout\fR is the address of where to place the result(s). This routine returns
\fB0\fR if it succeeds, or the value of \fBenum clnt_stat\fR cast to an integer
if it fails. The routine \fBclnt_perrno()\fR is handy for translating failure
statuses into messages. See \fBrpc_clnt_calls\fR(3NSL).
.sp
You do not have control of timeouts or authentication using this routine. This
routine exists for backward compatibility only, and is made obsolete by
\fBrpc_call()\fR. See \fBrpc_clnt_calls\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBclnt_stat_clnt_broadcast()\fR\fR
.ad
.RS 30n
Like \fBcallrpc()\fR, except the call message is broadcast to all locally
connected broadcast nets. Each time the caller receives a response, this
routine calls \fBeachresult()\fR, whose form is:
.sp
.in +2
.nf
\fBeachresult(char *\fIout\fR, struct sockaddr_in *\fIaddr\fR);\fR
.fi
.in -2

where \fIout\fR is the same as \fIout\fR passed to \fBclnt_broadcast()\fR,
except that the remote procedure's output is decoded there; \fIaddr\fR points
to the address of the machine that sent the results. If \fBeachresult()\fR
returns \fB0\fR, \fBclnt_broadcast()\fR waits for more replies; otherwise it
returns with appropriate status.  If \fBeachresult()\fR is \fBNULL\fR,
\fBclnt_broadcast()\fR returns without waiting for any replies.
.sp
Broadcast packets are limited in size to the maximum transfer unit of the
transports involved. For Ethernet, the caller's argument size is approximately
1500 bytes. Since the call message is sent to all connected networks, it may
potentially lead to broadcast storms. \fBclnt_broadcast()\fR uses \fBAUTH_SYS\fR
credentials by default. See \fBrpc_clnt_auth\fR(3NSL). This routine exists for
backward compatibility only, and is made obsolete by \fBrpc_broadcast()\fR. See
\fBrpc_clnt_calls\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBclntraw_create()\fR\fR
.ad
.RS 30n
This routine creates an internal, memory-based \fBRPC\fR client for the remote
program \fIprognum\fR, version \fIversnum\fR. The transport used to pass
messages to the service is actually a buffer within the process's address
space, so the corresponding \fBRPC\fR server should live in the same address
space. See \fBsvcraw_create()\fR. This allows simulation of \fBRPC\fR and
acquisition of \fBRPC\fR overheads, such as round trip times, without any
kernel interference. This routine returns \fBNULL\fR if it fails.
.sp
This routine exists for backward compatibility only. It has the same
functionality as \fBclnt_raw_create()\fR. See \fBrpc_clnt_create\fR(3NSL),
which obsoletes it.
.RE

.sp
.ne 2
.na
\fB\fBclnttcp_create()\fR\fR
.ad
.RS 30n
This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR,
version \fIversnum\fR; the client uses \fBTCP/IP\fR as a transport. The remote
program is located at Internet address \fIaddr\fR. If
\fIaddr\fR\fB\fR->\fIsin_port\fR is \fB0\fR, then it is set to the actual port
that the remote program is listening on. The remote \fBrpcbind\fR service is
consulted for this information. The parameter \fI*fdp\fR is a file descriptor,
which may be open and bound; if it is \fBRPC_ANYSOCK\fR, then this routine
opens a new one and sets \fI*fdp\fR. Refer to the \fBFile Descriptor\fR section
for more information. Since \fBTCP\fR-based \fBRPC\fR uses buffered \fBI/O\fR,
the user may specify the size of the send and receive buffers with the
parameters \fIsendsz\fR and \fIrecvsz\fR. Values of \fB0\fR choose suitable
defaults. This routine returns \fBNULL\fR if it fails.
.sp
This routine exists for backward compatibility only. \fBclnt_create()\fR,
\fBclnt_tli_create()\fR, or \fBclnt_vc_create()\fR should be used instead. See
\fBrpc_clnt_create\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBclntudp_bufcreate()\fR\fR
.ad
.RS 30n
Create a client handle for the remote program \fIprognum\fR, version
\fIversnum\fR;
the client uses \fBUDP/IP\fR as the transport. The remote program is located
at the Internet address \fIaddr\fR. If \fIaddr\fR->\fIsin_port\fR is \fB0\fR,
it is set to port on which the remote program is listening on (the remote
\fBrpcbind\fR service is consulted for this information). The parameter
\fI*fdp\fR is a file descriptor, which may be open and bound. If it is
\fBRPC_ANYSOCK\fR, then this routine opens a new one and sets \fI*fdp\fR. Refer
to the \fBFile Descriptor\fR section for more information. The \fBUDP\fR
transport resends the call message in intervals of \fBwait\fR time until a
response is received or until the call times out. The total time for the call
to time out is specified by \fBclnt_call()\fR. See \fBrpc_clnt_calls\fR(3NSL).
If successful it returns a client handle, otherwise it returns \fBNULL.\fR The
error can be printed using the \fBclnt_pcreateerror()\fR routine. See
\fBrpc_clnt_create\fR(3NSL).
.sp
The user can specify the maximum packet size for sending and receiving by using
\fIsendsz\fR and \fIrecvsz\fR arguments for \fBUDP\fR-based \fBRPC\fR messages.
.sp
If \fIaddr\fR->\fIsin_port\fR is \fB0\fR and the requested version number
\fIversnum\fR 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 \fBclnt_call()\fR later (see
\fBrpc_clnt_calls\fR(3NSL)).
.sp
This routine exists for backward compatibility only. \fBclnt_tli_create()\fR or
\fBclnt_dg_create()\fR should be used instead. See \fBrpc_clnt_create\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBclntudp_create()\fR\fR
.ad
.RS 30n
This routine creates an \fBRPC\fR client handle for the remote program
\fIprognum\fR, version \fIversnum\fR; the client uses \fBUDP/IP\fR as a
transport. The remote program is located at Internet address \fIaddr\fR. If
\fIaddr\fR->\fIsin_port\fR is \fB0\fR, then it is set to the actual port that the
remote program is listening on. The remote \fBrpcbind\fR service is consulted
for this information. The parameter \fI*fdp\fR is a file descriptor, which may
be open and bound; if it is \fBRPC_ANYSOCK\fR, then this routine opens a new
one and sets \fI*fdp\fR. Refer to the \fBFile Descriptor\fR section for more
information. The \fBUDP\fR transport resends the call message in intervals of
\fBwait\fR time until a response is received or until the call times out. The
total time for the call to time out is specified by \fBclnt_call()\fR. See
\fBrpc_clnt_calls\fR(3NSL). \fBclntudp_create()\fR returns a client handle on
success, otherwise it returns \fBNULL\fR. The error can be printed using the
\fBclnt_pcreateerror()\fR routine. See \fBrpc_clnt_create\fR(3NSL).
.sp
Since \fBUDP\fR-based \fBRPC\fR 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.
.sp
This routine exists for backward compatibility only. \fBclnt_create()\fR,
\fBclnt_tli_create()\fR, or \fBclnt_dg_create()\fR should be used instead. See
\fBrpc_clnt_create\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBget_myaddress()\fR\fR
.ad
.RS 30n
Places the local system's \fBIP\fR address into \fI*addr\fR, without consulting
the library routines that deal with \fB/etc/hosts\fR. The port number is always
set to \fBhtons(PMAPPORT)\fR.
.sp
This routine is only intended for use with the \fBRPC\fR library. It returns
the local system's address in a form compatible with the \fBRPC\fR library,
and should not be taken as the system's actual IP address. In fact, the
\fI*addr\fR 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.
.sp
This routine remains for backward compatibility only. The routine
\fBnetdir_getbyname()\fR should be used with the name \fBHOST_SELF\fR to
retrieve the local system's network address as a \fInetbuf\fR structure. See
\fBnetdir\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBgetrpcport()\fR\fR
.ad
.RS 30n
\fBgetrpcport()\fR returns the port number for the version \fIversnum\fR of the
\fBRPC\fR program \fIprognum\fR running on \fIhost\fR and using protocol
\fIproto\fR. \fBgetrpcport()\fR returns \fB0\fR if the \fBRPC\fR system
failed to contact the remote portmap service, the program associated with
\fIprognum\fR is not registered, or there is no mapping between the program and
a port.
.sp
This routine exists for backward compatibility only. Enhanced functionality is
provided by \fBrpcb_getaddr()\fR. See \fBrpcbind\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBpmaplist()\fR\fR
.ad
.RS 30n
A user interface to the \fBportmap\fR service, which returns a list of the
current \fBRPC\fR program-to-port mappings on the host located at \fBIP\fR
address \fIaddr\fR. This routine can return \fBNULL\fR. The command
`\fBrpcinfo\fR \fB-p\fR' uses this routine.
.sp
This routine exists for backward compatibility only, enhanced functionality is
provided by \fBrpcb_getmaps()\fR. See \fBrpcbind\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBpmap_getport()\fR\fR
.ad
.RS 30n
A user interface to the \fBportmap\fR service, which returns the port number
on which waits a service that supports program \fIprognum\fR, version
\fIversnum\fR, and speaks the transport protocol associated with
\fIprotocol\fR. The value of \fIprotocol\fR is most likely \fBIPPROTO_UDP\fR or
\fBIPPROTO_TCP\fR. A return value of \fB0\fR means that the mapping does not
exist or that the \fBRPC\fR system failed to contact the remote \fBportmap\fR
service.  In the latter case, the global variable \fBrpc_createerr\fR contains
the \fBRPC\fR status.
.sp
This routine exists for backward compatibility only, enhanced functionality is
provided by \fBrpcb_getaddr()\fR. See \fBrpcbind\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBpmap_rmtcall()\fR\fR
.ad
.RS 30n
Request that the \fBportmap\fR on the host at \fBIP\fR address \fI*addr\fR make
an \fBRPC\fR on the behalf of the caller to a procedure on that host.
\fI*portp\fR is modified to the program's port number if the procedure
succeeds. The definitions of other parameters are discussed in \fBcallrpc()\fR
and \fBclnt_call()\fR. See \fBrpc_clnt_calls\fR(3NSL).
.sp
This procedure is only available for the \fBUDP\fR transport.
.sp
If the requested remote procedure is not registered with the remote
\fBportmap\fR then no error response is returned and the call times out. Also,
no authentication is done.
.sp
This routine exists for backward compatibility only, enhanced functionality is
provided by \fBrpcb_rmtcall()\fR. See \fBrpcbind\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBpmap_set()\fR\fR
.ad
.RS 30n
A user interface to the \fBportmap\fR service, that establishes a mapping
between the triple [\fIprognum\fR, \fIversnum\fR, \fIprotocol\fR] and
\fIport\fR on the machine's \fBportmap\fR service.  The value of \fIprotocol\fR
may be \fBIPPROTO_UDP\fR or \fBIPPROTO_TCP\fR. Formerly, the routine failed if
the requested \fIport\fR was found to be in use.  Now, the routine only fails
if it finds that \fIport\fR is still bound.  If \fIport\fR is not bound, the
routine completes the requested registration.  This routine returns \fB1\fR if
it succeeds, \fB0\fR otherwise. Automatically done by \fBsvc_register()\fR.
.sp
This routine exists for backward compatibility only, enhanced functionality is
provided by \fBrpcb_set()\fR. See \fBrpcbind\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBpmap_unset()\fR\fR
.ad
.RS 30n
A user interface to the \fBportmap\fR service, which destroys all mapping
between the triple [\fIprognum\fR, \fIversnum\fR, \fIall-protocols\fR] and
\fIport\fR on the machine's \fBportmap\fR service.  This routine returns
\fB1\fR if it succeeds, \fB0\fR otherwise.
.sp
This routine exists for backward compatibility only, enhanced functionality is
provided by \fBrpcb_unset()\fR. See \fBrpcbind\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBsvc_fds()\fR\fR
.ad
.RS 30n
A global variable reflecting the \fBRPC\fR service side's read file descriptor
bit mask; it is suitable as a parameter to the \fBselect()\fR call. This is
only of interest if a service implementor does not call \fBsvc_run()\fR, but
rather does his own asynchronous event processing. This variable is read-only,
yet it may change after calls to \fBsvc_getreq()\fR or any creation routines.
Do not pass its address to \fBselect()\fR! Similar to \fBsvc_fdset\fR, but
limited to 32 descriptors.
.sp
This interface is made obsolete by \fBsvc_fdset\fR. See
\fBrpc_svc_calls\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBsvc_getcaller()\fR\fR
.ad
.RS 30n
This routine returns the network address, represented as a \fBstruct
sockaddr_in\fR, of the caller of a procedure associated with the \fBRPC\fR
service transport handle, \fIxprt\fR.
.sp
This routine exists for backward compatibility only, and is obsolete.  The
preferred interface is \fBsvc_getrpccaller()\fR. See \fBrpc_svc_reg\fR(3NSL),
which returns the address as a \fBstruct netbuf\fR.
.RE

.sp
.ne 2
.na
\fB\fBsvc_getreq()\fR\fR
.ad
.RS 30n
This routine is only of interest if a service implementor does not call
\fBsvc_run()\fR, but instead implements custom asynchronous event processing.
It is called when the \fBselect()\fR call has determined that an \fBRPC\fR
request has arrived on some \fBRPC\fR file descriptors; \fIrdfds\fR is the
resultant read file descriptor bit mask. The routine returns when all file
descriptors associated with the value of \fIrdfds\fR have been serviced. This
routine is similar to \fBsvc_getreqset()\fR but is limited to 32 descriptors.
.sp
This interface is made obsolete by \fBsvc_getreqset()\fR.
.RE

.sp
.ne 2
.na
\fBsvcfd_create\fB()\fR\fR
.ad
.RS 30n
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
\fBFile Descriptor\fR section for more information. \fIsendsz\fR and
\fIrecvsz\fR indicate sizes for the send and receive buffers. If they are
\fB0\fR, a reasonable default is chosen.
.sp
This interface is made obsolete by \fBsvc_fd_create()\fR (see
\fBrpc_svc_create\fR(3NSL)).
.RE

.sp
.ne 2
.na
\fB\fBsvcraw_create()\fR\fR
.ad
.RS 30n
This routine creates an internal, memory-based \fBRPC\fR service transport, to
which it returns a pointer. The transport is really a buffer within the
process's address space, so the corresponding \fBRPC\fR client should live in
the same address space; see \fBclntraw_create()\fR. This routine allows
simulation of \fBRPC\fR and acquisition of \fBRPC\fR overheads (such as round
trip times), without any kernel interference. This routine returns \fBNULL\fR
if it fails.
.sp
This routine exists for backward compatibility only, and has the same
functionality of \fBsvc_raw_create()\fR. See \fBrpc_svc_create\fR(3NSL), which
obsoletes it.
.RE

.sp
.ne 2
.na
\fB\fBsvctcp_create()\fR\fR
.ad
.RS 30n
This routine creates a \fBTCP/IP\fR-based \fBRPC\fR service transport, to which
it returns a pointer. The transport is associated with the file descriptor
\fIfd\fR, which may be \fBRPC_ANYSOCK\fR, in which case a new file descriptor
is created. If the file descriptor is not bound to a local \fBTCP\fR port, then
this routine binds it to an arbitrary port. Refer to the \fBFile Descriptor\fR
section for more information. Upon completion, \fIxprt\fR->\fBxp_fd\fR is the
transport's file descriptor, and \fIxprt\fR->\fBxp_port\fR is the transport's
port number. This routine returns \fBNULL\fR if it fails. Since \fBTCP\fR-based
\fBRPC\fR uses buffered \fBI/O\fR, users may specify the size of buffers;
values of \fB0\fR choose suitable defaults.
.sp
This routine exists for backward compatibility only. \fBsvc_create()\fR,
\fBsvc_tli_create()\fR, or \fBsvc_vc_create()\fR should be used instead. See
\fBrpc_svc_create\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBsvcudp_bufcreate()\fR\fR
.ad
.RS 30n
This routine creates a \fBUDP/IP\fR-based \fBRPC\fR service transport, to which
it returns a pointer. The transport is associated with the file descriptor
\fIfd\fR. If \fIfd\fR is \fBRPC_ANYSOCK\fR then a new file descriptor is
created. If the file descriptor is not bound to a local \fBUDP\fR port, then
this routine binds it to an arbitrary port. Upon completion,
\fIxprt\fR->\fBxp_fd\fR is the transport's file descriptor, and
\fIxprt\fR->\fBxp_port\fR is the transport's port number. Refer to the \fBFile
Descriptor\fR section for more information. This routine returns \fBNULL\fR if
it fails.
.sp
The user specifies the maximum packet size for sending and receiving
\fBUDP\fR-based
\fBRPC\fR messages by using the \fIsendsz\fR and \fIrecvsz\fR parameters.
.sp
This routine exists for backward compatibility only. \fBsvc_tli_create()\fR, or
\fBsvc_dg_create()\fR should be used instead. See \fBrpc_svc_create\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBsvcudp_create()\fR\fR
.ad
.RS 30n
This routine creates a \fBUDP/IP\fR-based \fBRPC\fR service transport, to which
it returns a pointer. The transport is associated with the file descriptor
\fIfd\fR, which may be \fBRPC_ANYSOCK\fR, in which case a new file descriptor
is created. If the file descriptor is not bound to a local \fBUDP\fR port, then
this routine binds it to an arbitrary port. Upon completion,
\fIxprt\fR->\fBxp_fd\fR is the transport's file descriptor, and
\fIxprt\fR->\fBxp_port\fR is the transport's port number. This routine returns
\fBNULL\fR if it fails.
.sp
Since \fBUDP\fR-based \fBRPC\fR 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.
.sp
This routine exists for backward compatibility only. \fBsvc_create()\fR,
\fBsvc_tli_create()\fR, or \fBsvc_dg_create()\fR should be used instead. See
\fBrpc_svc_create\fR(3NSL).
.RE

.sp
.ne 2
.na
\fB\fBregisterrpc()\fR\fR
.ad
.RS 30n
Register program \fIprognum\fR, procedure \fIprocnum\fR, and version
\fIversnum\fR with the \fBRPC\fR service package. If a request arrives for
program \fIprognum\fR, version \fIversnum\fR, and procedure \fIprocnum\fR,
\fIprocname\fR is called with a pointer to its parameter(s). \fIprocname\fR
should return a pointer to its static result(s). \fIinproc\fR is used to decode
the parameters while \fIoutproc\fR is used to encode the results. This routine
returns \fB0\fR if the registration succeeded, \(mi1 otherwise.
.sp
\fBsvc_run()\fR must be called after all the services are registered.
.sp
This routine exists for backward compatibility only, and it is made obsolete by
\fBrpc_reg()\fR.
.RE

.sp
.ne 2
.na
\fB\fBsvc_register()\fR\fR
.ad
.RS 30n
Associates \fIprognum\fR and \fIversnum\fR with the service dispatch procedure,
\fIdispatch\fR. If \fIprotocol\fR is \fB0\fR, the service is not registered
with the \fBportmap\fR service. If \fIprotocol\fR is non-zero, then a mapping
of the triple [\fIprognum\fR, \fIversnum\fR, \fIprotocol\fR] to
\fIxprt\fR->\fBxp_port\fR is established with the local \fBportmap\fR service
(generally \fIprotocol\fR is \fB0\fR, \fBIPPROTO_UDP\fR or \fBIPPROTO_TCP\fR).
The procedure \fIdispatch\fR has the following form:
.sp
.in +2
.nf
\fBdispatch(struct svc_req *\fIrequest\fR, SVCXPRT *\fIxprt\fR);\fR
.fi
.in -2

The \fBsvc_register()\fR routine returns one if it succeeds, and \fB0\fR
otherwise.
.sp
This routine exists for backward compatibility only. Enhanced functionality is
provided by \fBsvc_reg()\fR.
.RE

.sp
.ne 2
.na
\fB\fBsvc_unregister()\fR\fR
.ad
.RS 30n
Remove all mapping of the double [\fIprognum\fR, \fIversnum\fR] to dispatch
routines, and of the triple [\fIprognum\fR, \fIversnum\fR, \fIall-protocols\fR]
to port number from \fBportmap\fR.
.sp
This routine exists for backward compatibility. Enhanced functionality is
provided by \fBsvc_unreg()\fR.
.RE

.sp
.ne 2
.na
\fB\fBxdr_authunix_parms()\fR\fR
.ad
.RS 30n
Used for describing \fBUNIX\fR credentials. This routine is useful for users
who wish to generate these credentials without using the \fBRPC\fR
authentication package.
.sp
This routine exists for backward compatibility only, and is made obsolete by
\fBxdr_authsys_parms()\fR. See \fBrpc_xdr\fR(3NSL).
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.BR select (3C),
.BR libnsl (3LIB),
.BR netdir (3NSL),
.BR netdir_getbyname (3NSL),
.BR rpc (3NSL),
.BR rpc_clnt_auth (3NSL),
.BR rpc_clnt_calls (3NSL),
.BR rpc_clnt_create (3NSL),
.BR rpc_svc_calls (3NSL),
.BR rpc_svc_create (3NSL),
.BR rpc_svc_err (3NSL),
.BR rpc_svc_reg (3NSL),
.BR rpc_xdr (3NSL),
.BR rpcbind (3NSL),
.BR secure_rpc (3NSL),
.BR xdr_authsys_parms (3NSL),
.BR attributes (7),
.BR keyserv (8),
.BR rpcbind (8),
.BR rpcinfo (8)
.SH NOTES
These interfaces are unsafe in multithreaded applications.  Unsafe interfaces
should be called only from the main thread.