'\" 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 "Jun 7, 2001" .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 .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\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, 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 .na \fB\fBauthunix_create()\fR\fR .ad .RS 30n 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 .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 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 .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-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 .na \fB\fBclntudp_bufcreate()\fR\fR .ad .RS 30n 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 .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 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 .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 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 .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 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 .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 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 .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-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 .na \fB\fBsvcudp_bufcreate()\fR\fR .ad .RS 30n 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 .na \fB\fBsvcudp_create()\fR\fR .ad .RS 30n 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 .na \fB\fBregisterrpc()\fR\fR .ad .RS 30n 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 .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 .sp .LP See \fBattributes\fR(5) 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 .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.