diff options
Diffstat (limited to 'usr/src/man/man3nsl/rpc_soc.3nsl')
| -rw-r--r-- | usr/src/man/man3nsl/rpc_soc.3nsl | 890 |
1 files changed, 890 insertions, 0 deletions
diff --git a/usr/src/man/man3nsl/rpc_soc.3nsl b/usr/src/man/man3nsl/rpc_soc.3nsl new file mode 100644 index 0000000000..ac85ae5dda --- /dev/null +++ b/usr/src/man/man3nsl/rpc_soc.3nsl @@ -0,0 +1,890 @@ +'\" te +.\" 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 "7 Jun 2001" "SunOS 5.11" "Networking Services Library Functions" +.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 +.LP +.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); +.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 +\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, \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 +\fB\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 +.sp +.LP +\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" +.sp +.LP +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" +.sp +.LP +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 +.mk +.na +\fB\fBauthdes_create()\fR\fR +.ad +.RS 30n +.rt +\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, below. Note: the keyserver daemon +\fBkeyserv\fR(1M) 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 +.mk +.na +\fB\fBauthunix_create()\fR\fR +.ad +.RS 30n +.rt +Create and return an \fBRPC\fR authentication handle that contains .UX +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 +.mk +.na +\fB\fBauthunix_create_default()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBcallrpc()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBclnt_stat_clnt_broadcast()\fR\fR +.ad +.RS 30n +.rt +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 callers 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 SB AUTH_SYS +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 +.mk +.na +\fB\fBclntraw_create()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBclnttcp_create()\fR\fR +.ad +.RS 30n +.rt +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-based\fR \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 +.mk +.na +\fB\fBclntudp_bufcreate()\fR\fR +.ad +.RS 30n +.rt +Create a client handle for the remote program \fIprognum\fR, on \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-based\fR \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 +.mk +.na +\fB\fBclntudp_create()\fR\fR +.ad +.RS 30n +.rt +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 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-based\fR \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 +.mk +.na +\fB\fBget_myaddress()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBgetrpcport()\fR\fR +.ad +.RS 30n +.rt +\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 +.mk +.na +\fB\fBpmaplist()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBpmap_getport()\fR\fR +.ad +.RS 30n +.rt +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 failured to contact the remote \fBportmap\fR +service. In the latter case, the global variable \fBrpc_createerr\fR contains +the \fB RPC\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 +.mk +.na +\fB\fBpmap_rmtcall()\fR\fR +.ad +.RS 30n +.rt +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 UDP 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 +.mk +.na +\fB\fBpmap_set()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBpmap_unset()\fR\fR +.ad +.RS 30n +.rt +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 one 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 +.mk +.na +\fB\fBsvc_fds()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBsvc_getcaller()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBsvc_getreq()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fBsvcfd_create\fB()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBsvcraw_create()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBsvctcp_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates a \fBTCP/IP-based\fR \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-based\fR +\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 +.mk +.na +\fB\fBsvcudp_bufcreate()\fR\fR +.ad +.RS 30n +.rt +This routine creates a \fBUDP/IP-based\fR \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 UDP-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 +.mk +.na +\fB\fBsvcudp_create()\fR\fR +.ad +.RS 30n +.rt +This routine creates a \fBUDP/IP-based\fR \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-based\fR \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 +.mk +.na +\fB\fBregisterrpc()\fR\fR +.ad +.RS 30n +.rt +Register program \fIprognum\fR, procedure \fIprocname\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 +.mk +.na +\fB\fBsvc_register()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBsvc_unregister()\fR\fR +.ad +.RS 30n +.rt +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 +.mk +.na +\fB\fBxdr_authunix_parms()\fR\fR +.ad +.RS 30n +.rt +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 +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBkeyserv\fR(1M), \fBrpcbind\fR(1M), \fBrpcinfo\fR(1M), \fBnetdir\fR(3NSL), +\fBnetdir_getbyname\fR(3NSL), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), +\fBrpc_clnt_calls\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), +\fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL), +\fBrpc_svc_reg\fR(3NSL), \fBrpc_xdr\fR(3NSL), \fBrpcbind\fR(3NSL), +\fBsecure_rpc\fR(3NSL), \fBselect\fR(3C), \fBxdr_authsys_parms\fR(3NSL), +\fBlibnsl\fR(3LIB), \fBlibrpcsoc\fR(3LIBUCB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +These interfaces are unsafe in multithreaded applications. Unsafe interfaces +should be called only from the main thread. |