usr/src/man/man3nsl/rpc_soc.3nsl

   1 '\" te
   2 .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
   3 .\" Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH RPC_SOC 3NSL "May 13, 2017"
   8 .SH NAME
   9 rpc_soc, authdes_create, authunix_create, authunix_create_default, callrpc,
  10 clnt_broadcast, clntraw_create, clnttcp_create, clntudp_bufcreate,
  11 clntudp_create, get_myaddress, getrpcport, pmap_getmaps, pmap_getport,
  12 pmap_rmtcall, pmap_set, pmap_unset, registerrpc, svc_fds, svc_getcaller,
  13 svc_getreq, svc_register, svc_unregister, svcfd_create, svcraw_create,
  14 svctcp_create, svcudp_bufcreate, svcudp_create, xdr_authunix_parms \- obsolete
  15 library routines for RPC
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 #define PORTMAP
  20 #include <rpc/rpc.h>
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBAUTH *\fR\fBauthdes_create\fR(\fBchar *\fR\fIname\fR, \fBuint_t\fR \fIwindow\fR,
  26      \fBstruct sockaddr_in *\fR\fIsyncaddr\fR, \fBdes_block *\fR\fIckey\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBAUTH *\fR\fBauthunix_create\fR(\fBchar *\fR\fIhost\fR, \fBuid_t\fR \fIuid\fR, \fBgid_t\fR \fIgid\fR,
  32      \fBint\fR \fIgrouplen\fR, \fBgid_t *\fR\fIgidlistp\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBAUTH *\fR\fBauthunix_create_default\fR(void)
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBcallrpc\fR(\fBchar *\fR\fIhost\fR, \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
  43      \fBrpcproc_t\fR \fIprocnum\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBchar *\fR\fIin\fR,
  44      \fBxdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBenum\fR \fBclnt_stat_clnt_broadcast\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
  50      \fBrpcproc_t\fR \fIprocnum\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBchar *\fR\fIin\fR,
  51      \fBxdrproc_t\fR \fIoutproc\fR, \fBchar *\fR\fIout\fR, \fBresultproc_t\fR\fIeachresult\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBCLIENT *\fR\fBclntraw_create\fR(\fBrpcproc_t\fR \fIprocnum\fR, \fBrpcvers_t\fR \fIversnum\fR);
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBCLIENT *\fR\fBclnttcp_create\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
  62      \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, \fBint *\fR\fIfdp\fR,
  63      \fBuint_t\fR \fIsendz\fR, \fBuint_t\fR \fIrecvsz\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBCLIENT *\fR\fBclntudp_bufcreate\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR, \fBrpcprog_t\fR \fIprognum\fR,
  69      \fBrpcvers_t\fR \fIversnum\fR, \fBstruct timeval\fR \fIwait\fR,
  70      \fBint *\fR\fIfdp\fR, \fBuint_t\fR \fIsendz\fR, \fBuint_t\fR \fIrecvsz\fR);
  71 .fi
  72
  73 .LP
  74 .nf
  75 \fBCLIENT *\fR\fBclntudp_create\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
  76      \fBrpcprog_t\fR \fIprognum\fR, \fBstruct timeval\fR \fIwait\fR, \fBint *\fR\fIfdp\fR);
  77 .fi
  78
  79 .LP
  80 .nf
  81 \fBvoid\fR \fBget_myaddress\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR);
  82 .fi
  83
  84 .LP
  85 .nf
  86 \fBushort\fR \fBgetrpcport\fR(\fBchar *\fR\fIhost\fR, \fBrpcprog_t\fR \fIprognum\fR,
  87      \fBrpcvers_t\fR \fIversnum\fR, \fBrpcprot_t\fR \fIproto\fR);
  88 .fi
  89
  90 .LP
  91 .nf
  92 \fBstruct pmaplist *\fR\fBpmap_getmaps\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR);
  93 .fi
  94
  95 .LP
  96 .nf
  97 \fBushort\fR \fBpmap_getport\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
  98      \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
  99      \fBrpcprot_t\fR \fIprotocol\fR);
 100 .fi
 101
 102 .LP
 103 .nf
 104 \fBenum clnt_stat\fR \fBpmap_rmtcall\fR(\fBstruct sockaddr_in *\fR\fIaddr\fR,
 105      \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
 106      \fBrpcproc_t\fR \fIprogcnum\fR, \fBcaddr_t\fR \fIin\fR, \fBxdrproct_t\fR \fIinproc\fR,
 107      \fBcaddr_t\fR \fIout\fR, \fBcdrproct_t\fR \fIoutproc\fR,
 108      \fBstruct timeval\fR \fItout\fR, \fBrpcport_t *\fR\fIportp\fR);
 109 .fi
 110
 111 .LP
 112 .nf
 113 \fBbool_t\fR \fBpmap_set\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
 114      \fBrpcprot_t\fR \fIprotocol\fR, \fBu_short\fR \fIport\fR);
 115 .fi
 116
 117 .LP
 118 .nf
 119 \fBbool_t\fR \fBpmap_unset\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR);
 120 .fi
 121
 122 .LP
 123 .nf
 124 int svc_fds;
 125 .fi
 126
 127 .LP
 128 .nf
 129 \fBstruct sockaddr_in *\fR\fBsvc_getcaller\fR(\fBSVCXPRT *\fR\fIxprt\fR);
 130 .fi
 131
 132 .LP
 133 .nf
 134 \fBvoid\fR \fBsvc_getreq\fR(\fBint\fR \fIrdfds\fR);
 135 .fi
 136
 137 .LP
 138 .nf
 139 \fBSVCXPRT *\fR\fBsvcfd_create\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR,
 140      \fBuint_t\fR \fIrecvsz\fR);
 141 .fi
 142
 143 .LP
 144 .nf
 145 \fBSVCXPRT *\fR\fBsvcraw_create\fR(void)
 146 .fi
 147
 148 .LP
 149 .nf
 150 \fBSVCXPRT *\fR\fBsvctcp_create\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR,
 151      \fBuint_t\fR \fIrecvsz\fR);
 152 .fi
 153
 154 .LP
 155 .nf
 156 \fBSVCXPRT *\fR\fBsvcudp_bufcreate\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIsendsz\fR,
 157      \fBuint_t\fR \fIrecvsz\fR);
 158 .fi
 159
 160 .LP
 161 .nf
 162 \fBSVCXPRT *\fR\fBsvcudp_create\fR(\fBint\fR \fIfd\fR);
 163 .fi
 164
 165 .LP
 166 .nf
 167 \fB\fR\fBregisterrpc\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR, \fBrpcproc_t\fR \fIprocnum\fR,
 168      \fBchar *(*procname)()\fR, \fBxdrproc_t\fR \fIinproc\fR, \fBxdrproc_t\fR \fIoutproc\fR);
 169 .fi
 170
 171 .LP
 172 .nf
 173 \fBbool_t\fR\fBsvc_register\fR(\fBSVCXPRT *\fR\fIxprt\fR, \fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR,
 174      \fBvoid (*\fR\fIdispatch()\fR, \fBint\fR \fIprotocol\fR);
 175 .fi
 176
 177 .LP
 178 .nf
 179 \fBvoid\fR \fBsvc_unregister\fR(\fBrpcprog_t\fR \fIprognum\fR, \fBrpcvers_t\fR \fIversnum\fR);
 180 .fi
 181
 182 .LP
 183 .nf
 184 \fBbool_t\fR \fBxdr_authunix_parms\fR(\fBXDR *\fR\fIxdrs\fR, \fBstruct authunix_parms *\fR\fIsupp\fR);
 185 .fi
 186
 187 .SH DESCRIPTION
 188 .LP
 189 \fBRPC\fR routines allow C programs to make procedure calls on other machines
 190 across the network. First, the client calls a procedure to send a request to
 191 the server. Upon receipt of the request, the server calls a dispatch routine to
 192 perform the requested service, and then sends back a reply. Finally, the
 193 procedure call returns to the client.
 194 .sp
 195 .LP
 196 The routines described in this manual page have been superseded by other
 197 routines. The preferred routine is given after the description of the routine.
 198 New programs should use the preferred routines, as support for the older
 199 interfaces may be dropped in future releases.
 200 .SS "File Descriptors"
 201 .LP
 202 Transport independent \fBRPC\fR uses \fBTLI\fR as its transport interface
 203 instead of sockets.
 204 .sp
 205 .LP
 206 Some of the routines described in this section (such as \fBclnttcp_create()\fR)
 207 take a pointer to a file descriptor as one of the parameters. If the user wants
 208 the file descriptor to be a socket, then the application will have to be linked
 209 with both \fBlibrpcsoc\fR and \fBlibnsl\fR. If the user passed
 210 \fBRPC_ANYSOCK\fR as the file descriptor, and the application is linked with
 211 \fBlibnsl\fR only, then the routine will return a \fBTLI\fR file descriptor
 212 and not a socket.
 213 .SS "Routines"
 214 .LP
 215 The following routines require that the header \fB<rpc/rpc.h>\fR be included.
 216 The symbol \fBPORTMAP\fR should be defined so that the appropriate function
 217 declarations for the old interfaces are included through the header files.
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBauthdes_create()\fR\fR
 222 .ad
 223 .RS 30n
 224 \fBauthdes_create()\fR is the first of two routines which interface to the
 225 \fBRPC\fR secure authentication system, known as \fBDES\fR authentication. The
 226 second is \fBauthdes_getucred()\fR, below.  Note: the keyserver daemon
 227 \fBkeyserv\fR(1M) must be running for the \fBDES\fR authentication system to
 228 work.
 229 .sp
 230 \fBauthdes_create()\fR, used on the client side, returns an authentication
 231 handle that will enable the use of the secure authentication system. The first
 232 parameter \fIname\fR is the network name, or \fInetname\fR, of the owner of the
 233 server process.  This field usually represents a hostname derived from the
 234 utility routine \fBhost2netname()\fR, but could also represent a user name
 235 using \fBuser2netname()\fR. See \fBsecure_rpc\fR(3NSL). The second field is
 236 window on the validity of the client credential, given in seconds.  A small
 237 window is more secure than a large one, but choosing too small of a window
 238 will increase the frequency of resynchronizations because of clock drift.  The
 239 third parameter \fIsyncaddr\fR is optional.  If it is \fBNULL,\fR then the
 240 authentication system will assume that the local clock is always in sync with
 241 the server's clock, and will not attempt resynchronizations. If an address is
 242 supplied, however, then the system will use the address for consulting the
 243 remote time service whenever resynchronization is required.  This parameter is
 244 usually the address of the \fBRPC\fR server itself. The final parameter
 245 \fIckey\fR is also optional. If it is \fBNULL,\fR then the authentication
 246 system will generate a random \fBDES\fR key to be used for the encryption of
 247 credentials. If it is supplied, however, then it will be used instead.
 248 .sp
 249 This routine exists for backward compatibility only, and it is made obsolete by
 250 \fBauthdes_seccreate()\fR. See \fBsecure_rpc\fR(3NSL).
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBauthunix_create()\fR\fR
 257 .ad
 258 .RS 30n
 259 Create and return an \fBRPC\fR authentication handle that contains .UX
 260 authentication information. The parameter \fIhost\fR is the name of the machine
 261 on which the information was created; \fIuid\fR is the user's user \fBID;\fR
 262 \fIgid\fR is the user's current group \fBID;\fR \fIgrouplen\fR and
 263 \fIgidlistp\fR refer to a counted array of groups to which the user belongs.
 264 .sp
 265 It is not very difficult to impersonate a user.
 266 .sp
 267 This routine exists for backward compatibility only, and it is made obsolete by
 268 \fBauthsys_create()\fR. See \fBrpc_clnt_auth\fR(3NSL).
 269 .RE
 270
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fBauthunix_create_default()\fR\fR
 275 .ad
 276 .RS 30n
 277 Call \fBauthunix_create()\fR with the appropriate parameters.
 278 .sp
 279 This routine exists for backward compatibility only, and it is made obsolete by
 280 \fBauthsys_create_default()\fR. See \fBrpc_clnt_auth\fR(3NSL).
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBcallrpc()\fR\fR
 287 .ad
 288 .RS 30n
 289 Call the remote procedure associated with \fIprognum\fR, \fIversnum\fR, and
 290 \fIprocnum\fR on the machine, \fIhost\fR. The parameter \fIinproc\fR is used to
 291 encode the procedure's parameters, and \fIoutproc\fR is used to decode the
 292 procedure's results; \fIin\fR is the address of the procedure's argument, and
 293 \fIout\fR is the address of where to place the result(s). This routine returns
 294 \fB0\fR if it succeeds, or the value of \fBenum clnt_stat\fR cast to an integer
 295 if it fails. The routine \fBclnt_perrno()\fR is handy for translating failure
 296 statuses into messages. See \fBrpc_clnt_calls\fR(3NSL).
 297 .sp
 298 You do not have control of timeouts or authentication using this routine. This
 299 routine exists for backward compatibility only, and is made obsolete by
 300 \fBrpc_call()\fR. See \fBrpc_clnt_calls\fR(3NSL).
 301 .RE
 302
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBclnt_stat_clnt_broadcast()\fR\fR
 307 .ad
 308 .RS 30n
 309 Like \fBcallrpc()\fR, except the call message is broadcast to all locally
 310 connected broadcast nets. Each time the caller receives a response, this
 311 routine calls \fBeachresult()\fR, whose form is:
 312 .sp
 313 .in +2
 314 .nf
 315 \fBeachresult(char *\fIout\fR, struct sockaddr_in *\fIaddr\fR);\fR
 316 .fi
 317 .in -2
 318
 319 where \fIout\fR is the same as \fIout\fR passed to \fBclnt_broadcast()\fR,
 320 except that the remote procedure's output is decoded there; \fIaddr\fR points
 321 to the address of the machine that sent the results. If \fBeachresult()\fR
 322 returns \fB0\fR, \fBclnt_broadcast()\fR waits for more replies; otherwise it
 323 returns with appropriate status.  If \fBeachresult()\fR is \fBNULL,\fR
 324 \fBclnt_broadcast()\fR returns without waiting for any replies.
 325 .sp
 326 Broadcast packets are limited in size to the maximum transfer unit of the
 327 transports involved. For Ethernet, the callers argument size is approximately
 328 1500 bytes. Since the call message is sent to all connected networks, it may
 329 potentially lead to broadcast storms. \fBclnt_broadcast()\fR uses SB AUTH_SYS
 330 credentials by default. See \fBrpc_clnt_auth\fR(3NSL). This routine exists for
 331 backward compatibility only, and is made obsolete by \fBrpc_broadcast()\fR. See
 332 \fBrpc_clnt_calls\fR(3NSL).
 333 .RE
 334
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fBclntraw_create()\fR\fR
 339 .ad
 340 .RS 30n
 341 This routine creates an internal, memory-based \fBRPC\fR client for the remote
 342 program \fIprognum\fR, version \fIversnum\fR. The transport used to pass
 343 messages to the service is actually a buffer within the process's address
 344 space, so the corresponding \fBRPC\fR server should live in the same address
 345 space. See \fBsvcraw_create()\fR. This allows simulation of \fBRPC\fR and
 346 acquisition of \fBRPC\fR overheads, such as round trip times, without any
 347 kernel interference. This routine returns \fBNULL\fR if it fails.
 348 .sp
 349 This routine exists for backward compatibility only. It has the same
 350 functionality as \fBclnt_raw_create()\fR. See \fBrpc_clnt_create\fR(3NSL),
 351 which obsoletes it.
 352 .RE
 353
 354 .sp
 355 .ne 2
 356 .na
 357 \fB\fBclnttcp_create()\fR\fR
 358 .ad
 359 .RS 30n
 360 This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR,
 361 version \fIversnum\fR; the client uses \fBTCP/IP\fR as a transport. The remote
 362 program is located at Internet address \fIaddr\fR. If
 363 \fIaddr\fR\fB\fR->\fIsin_port\fR is \fB0\fR, then it is set to the actual port
 364 that the remote program is listening on. The remote \fBrpcbind\fR service is
 365 consulted for this information. The parameter \fI*fdp\fR is a file descriptor,
 366 which may be open and bound; if it is \fBRPC_ANYSOCK\fR, then this routine
 367 opens a new one and sets \fI*fdp\fR. Refer to the \fBFile Descriptor\fR section
 368 for more information. Since \fBTCP-based\fR \fBRPC\fR uses buffered \fBI/O,\fR
 369 the user may specify the size of the send and receive buffers with the
 370 parameters \fIsendsz\fR and \fIrecvsz\fR. Values of \fB0\fR choose suitable
 371 defaults. This routine returns \fBNULL\fR if it fails.
 372 .sp
 373 This routine exists for backward compatibility only. \fBclnt_create()\fR,
 374 \fBclnt_tli_create()\fR, or \fBclnt_vc_create()\fR should be used instead. See
 375 \fBrpc_clnt_create\fR(3NSL).
 376 .RE
 377
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fBclntudp_bufcreate()\fR\fR
 382 .ad
 383 .RS 30n
 384 Create a client handle for the remote program \fIprognum\fR, on \fIversnum\fR;
 385 the client uses \fBUDP/IP\fR as the transport. The remote program is located
 386 at the Internet address \fIaddr\fR. If \fIaddr\fR->\fIsin_port\fR is \fB0\fR,
 387 it is set to port on which the remote program is listening on (the remote
 388 \fBrpcbind\fR service is consulted for this information). The parameter
 389 \fI*fdp\fR is a file descriptor, which may be open and bound. If it is
 390 \fBRPC_ANYSOCK\fR, then this routine opens a new one and sets \fI*fdp\fR. Refer
 391 to the \fBFile Descriptor\fR section for more information. The \fBUDP\fR
 392 transport resends the call message in intervals of \fBwait\fR time until a
 393 response is received or until the call times out. The total time for the call
 394 to time out is specified by \fBclnt_call()\fR. See \fBrpc_clnt_calls\fR(3NSL).
 395 If successful it returns a client handle, otherwise it returns \fBNULL.\fR The
 396 error can be printed using the \fBclnt_pcreateerror()\fR routine. See
 397 \fBrpc_clnt_create\fR(3NSL).
 398 .sp
 399 The user can specify the maximum packet size for sending and receiving by using
 400 \fIsendsz\fR and \fIrecvsz\fR arguments for \fBUDP-based\fR \fBRPC\fR messages.
 401 .sp
 402 If \fIaddr\fR->\fIsin_port\fR is \fB0\fR and the requested version number
 403 \fIversnum\fR is not registered with the remote portmap service, it returns a
 404 handle if at least a version number for the given program number is registered.
 405 The version mismatch is discovered by a \fBclnt_call()\fR later (see
 406 \fBrpc_clnt_calls\fR(3NSL)).
 407 .sp
 408 This routine exists for backward compatibility only. \fBclnt_tli_create()\fR or
 409 \fBclnt_dg_create()\fR should be used instead. See \fBrpc_clnt_create\fR(3NSL).
 410 .RE
 411
 412 .sp
 413 .ne 2
 414 .na
 415 \fB\fBclntudp_create()\fR\fR
 416 .ad
 417 .RS 30n
 418 This routine creates an \fBRPC\fR client handle for the remote program
 419 \fIprognum\fR, version \fIversnum\fR; the client uses \fBUDP/IP\fR as a
 420 transport. The remote program is located at Internet address \fIaddr\fR. If
 421 \fIaddr\fR->\fIsin_port\fR is \fB0\fR, then it is set to actual port that the
 422 remote program is listening on. The remote \fBrpcbind\fR service is consulted
 423 for this information. The parameter \fI*fdp\fR is a file descriptor, which may
 424 be open and bound; if it is \fBRPC_ANYSOCK\fR, then this routine opens a new
 425 one and sets \fI*fdp\fR. Refer to the \fBFile Descriptor\fR section for more
 426 information. The \fBUDP\fR transport resends the call message in intervals of
 427 \fBwait\fR time until a response is received or until the call times out. The
 428 total time for the call to time out is specified by \fBclnt_call()\fR. See
 429 \fBrpc_clnt_calls\fR(3NSL). \fBclntudp_create()\fR returns a client handle on
 430 success, otherwise it returns \fBNULL\fR. The error can be printed using the
 431 \fBclnt_pcreateerror()\fR routine. See \fBrpc_clnt_create\fR(3NSL).
 432 .sp
 433 Since \fBUDP-based\fR \fBRPC\fR messages can only hold up to 8 Kbytes of
 434 encoded data, this transport cannot be used for procedures that take large
 435 arguments or return huge results.
 436 .sp
 437 This routine exists for backward compatibility only. \fBclnt_create()\fR,
 438 \fBclnt_tli_create()\fR, or \fBclnt_dg_create()\fR should be used instead. See
 439 \fBrpc_clnt_create\fR(3NSL).
 440 .RE
 441
 442 .sp
 443 .ne 2
 444 .na
 445 \fB\fBget_myaddress()\fR\fR
 446 .ad
 447 .RS 30n
 448 Places the local system's \fBIP\fR address into \fI*addr\fR, without consulting
 449 the library routines that deal with \fB/etc/hosts\fR. The port number is always
 450 set to \fBhtons(PMAPPORT)\fR.
 451 .sp
 452 This routine is only intended for use with the \fBRPC\fR library. It returns
 453 the local system's address in a form compatible with the \fBRPC\fR library,
 454 and should not be taken as the system's actual IP address. In fact, the
 455 \fI*addr\fR buffer's host address part is actually zeroed. This address may
 456 have only local significance and should not be assumed to be an address that
 457 can be used to connect to the local system by remote systems or processes.
 458 .sp
 459 This routine remains for backward compatibility only. The routine
 460 \fBnetdir_getbyname()\fR should be used with the name \fBHOST_SELF\fR to
 461 retrieve the local system's network address as a \fInetbuf\fR structure. See
 462 \fBnetdir\fR(3NSL).
 463 .RE
 464
 465 .sp
 466 .ne 2
 467 .na
 468 \fB\fBgetrpcport()\fR\fR
 469 .ad
 470 .RS 30n
 471 \fBgetrpcport()\fR returns the port number for the version \fIversnum\fR of the
 472 \fBRPC\fR program \fIprognum\fR running on \fIhost\fR and using protocol
 473 \fIproto\fR. \fBgetrpcport()\fR returns \fB0\fR if the \fBRPC\fR system
 474 failed to contact the remote portmap service, the program associated with
 475 \fIprognum\fR is not registered, or there is no mapping between the program and
 476 a port.
 477 .sp
 478 This routine exists for backward compatibility only. Enhanced functionality is
 479 provided by \fBrpcb_getaddr()\fR. See \fBrpcbind\fR(3NSL).
 480 .RE
 481
 482 .sp
 483 .ne 2
 484 .na
 485 \fB\fBpmaplist()\fR\fR
 486 .ad
 487 .RS 30n
 488 A user interface to the \fBportmap\fR service, which returns a list of the
 489 current \fBRPC\fR program-to-port mappings on the host located at \fBIP\fR
 490 address \fIaddr\fR. This routine can return \fBNULL .\fR The command
 491 `\fBrpcinfo\fR\fB-p\fR' uses this routine.
 492 .sp
 493 This routine exists for backward compatibility only, enhanced functionality is
 494 provided by \fBrpcb_getmaps()\fR. See \fBrpcbind\fR(3NSL).
 495 .RE
 496
 497 .sp
 498 .ne 2
 499 .na
 500 \fB\fBpmap_getport()\fR\fR
 501 .ad
 502 .RS 30n
 503 A user interface to the \fBportmap\fR service, which returns the port number
 504 on which waits a service that supports program \fIprognum\fR, version
 505 \fIversnum\fR, and speaks the transport protocol associated with
 506 \fIprotocol\fR. The value of \fIprotocol\fR is most likely \fBIPPROTO_UDP\fR or
 507 \fBIPPROTO_TCP\fR. A return value of \fB0\fR means that the mapping does not
 508 exist or that the \fBRPC\fR system failured to contact the remote \fBportmap\fR
 509 service.  In the latter case, the global variable \fBrpc_createerr\fR contains
 510 the \fB RPC\fR status.
 511 .sp
 512 This routine exists for backward compatibility only, enhanced functionality is
 513 provided by \fBrpcb_getaddr()\fR. See \fBrpcbind\fR(3NSL).
 514 .RE
 515
 516 .sp
 517 .ne 2
 518 .na
 519 \fB\fBpmap_rmtcall()\fR\fR
 520 .ad
 521 .RS 30n
 522 Request that the \fBportmap\fR on the host at \fBIP\fR address \fI*addr\fR make
 523 an \fBRPC\fR on the behalf of the caller to a procedure on that host.
 524 \fI*portp\fR is modified to the program's port number if the procedure
 525 succeeds. The definitions of other parameters are discussed in \fBcallrpc()\fR
 526 and \fBclnt_call()\fR. See \fBrpc_clnt_calls\fR(3NSL).
 527 .sp
 528 This procedure is only available for the UDP transport.
 529 .sp
 530 If the requested remote procedure is not registered with the remote
 531 \fBportmap\fR then no error response is returned and the call times out. Also,
 532 no authentication is done.
 533 .sp
 534 This routine exists for backward compatibility only, enhanced functionality is
 535 provided by \fBrpcb_rmtcall()\fR. See \fBrpcbind\fR(3NSL).
 536 .RE
 537
 538 .sp
 539 .ne 2
 540 .na
 541 \fB\fBpmap_set()\fR\fR
 542 .ad
 543 .RS 30n
 544 A user interface to the \fBportmap\fR service, that establishes a mapping
 545 between the triple [\fIprognum\fR, \fIversnum\fR, \fIprotocol\fR] and
 546 \fIport\fR on the machine's \fBportmap\fR service.  The value of \fIprotocol\fR
 547 may be \fBIPPROTO_UDP\fR or \fBIPPROTO_TCP\fR. Formerly, the routine failed if
 548 the requested \fIport\fR was found to be in use.  Now, the routine only fails
 549 if it finds that \fIport\fR is still bound.  If \fIport\fR is not bound, the
 550 routine completes the requested registration.  This routine returns \fB1\fR if
 551 it succeeds, \fB0\fR otherwise. Automatically done by \fBsvc_register()\fR.
 552 .sp
 553 This routine exists for backward compatibility only, enhanced functionality is
 554 provided by \fBrpcb_set()\fR. See \fBrpcbind\fR(3NSL).
 555 .RE
 556
 557 .sp
 558 .ne 2
 559 .na
 560 \fB\fBpmap_unset()\fR\fR
 561 .ad
 562 .RS 30n
 563 A user interface to the \fBportmap\fR service, which destroys all mapping
 564 between the triple [\fIprognum\fR, \fIversnum\fR, \fIall-protocols\fR] and
 565 \fIport\fR on the machine's \fBportmap\fR service.  This routine returns one if
 566 it succeeds, \fB0\fR otherwise.
 567 .sp
 568 This routine exists for backward compatibility only, enhanced functionality is
 569 provided by \fBrpcb_unset()\fR. See \fBrpcbind\fR(3NSL).
 570 .RE
 571
 572 .sp
 573 .ne 2
 574 .na
 575 \fB\fBsvc_fds()\fR\fR
 576 .ad
 577 .RS 30n
 578 A global variable reflecting the \fBRPC\fR service side's read file descriptor
 579 bit mask; it is suitable as a parameter to the \fBselect()\fR call. This is
 580 only of interest if a service implementor does not call \fBsvc_run()\fR, but
 581 rather does his own asynchronous event processing. This variable is read-only ,
 582 yet it may change after calls to \fBsvc_getreq()\fR or any creation routines.
 583 Do not pass its address to \fBselect()\fR! Similar to \fBsvc_fdset\fR, but
 584 limited to 32 descriptors.
 585 .sp
 586 This interface is made obsolete by \fBsvc_fdset\fR. See
 587 \fBrpc_svc_calls\fR(3NSL).
 588 .RE
 589
 590 .sp
 591 .ne 2
 592 .na
 593 \fB\fBsvc_getcaller()\fR\fR
 594 .ad
 595 .RS 30n
 596 This routine returns the network address, represented as a \fBstruct
 597 sockaddr_in\fR, of the caller of a procedure associated with the \fBRPC\fR
 598 service transport handle, \fIxprt\fR.
 599 .sp
 600 This routine exists for backward compatibility only, and is obsolete.  The
 601 preferred interface is \fBsvc_getrpccaller()\fR. See \fBrpc_svc_reg\fR(3NSL),
 602 which returns the address as a \fBstruct netbuf\fR.
 603 .RE
 604
 605 .sp
 606 .ne 2
 607 .na
 608 \fB\fBsvc_getreq()\fR\fR
 609 .ad
 610 .RS 30n
 611 This routine is only of interest if a service implementor does not call
 612 \fBsvc_run()\fR, but instead implements custom asynchronous event processing.
 613 It is called when the \fBselect()\fR call has determined that an \fBRPC\fR
 614 request has arrived on some \fBRPC\fR file descriptors; \fIrdfds\fR is the
 615 resultant read file descriptor bit mask. The routine returns when all file
 616 descriptors associated with the value of \fIrdfds\fR have been serviced. This
 617 routine is similar to \fBsvc_getreqset()\fR but is limited to 32 descriptors.
 618 .sp
 619 This interface is made obsolete by \fBsvc_getreqset()\fR.
 620 .RE
 621
 622 .sp
 623 .ne 2
 624 .na
 625 \fBsvcfd_create\fB()\fR\fR
 626 .ad
 627 .RS 30n
 628 Create a service on top of any open and bound descriptor. Typically, this
 629 descriptor is a connected file descriptor for a stream protocol. Refer to the
 630 \fBFile Descriptor\fR section for more information. \fIsendsz\fR and
 631 \fIrecvsz\fR indicate sizes for the send and receive buffers. If they are
 632 \fB0\fR, a reasonable default is chosen.
 633 .sp
 634 This interface is made obsolete by \fBsvc_fd_create()\fR (see
 635 \fBrpc_svc_create\fR(3NSL)).
 636 .RE
 637
 638 .sp
 639 .ne 2
 640 .na
 641 \fB\fBsvcraw_create()\fR\fR
 642 .ad
 643 .RS 30n
 644 This routine creates an internal, memory-based \fBRPC\fR service transport, to
 645 which it returns a pointer. The transport is really a buffer within the
 646 process's address space, so the corresponding \fBRPC\fR client should live in
 647 the same address space; see \fBclntraw_create()\fR. This routine allows
 648 simulation of \fBRPC\fR and acquisition of \fBRPC\fR overheads (such as round
 649 trip times), without any kernel interference. This routine returns \fBNULL\fR
 650 if it fails.
 651 .sp
 652 This routine exists for backward compatibility only, and has the same
 653 functionality of \fBsvc_raw_create()\fR. See \fBrpc_svc_create\fR(3NSL), which
 654 obsoletes it.
 655 .RE
 656
 657 .sp
 658 .ne 2
 659 .na
 660 \fB\fBsvctcp_create()\fR\fR
 661 .ad
 662 .RS 30n
 663 This routine creates a \fBTCP/IP-based\fR \fBRPC\fR service transport, to which
 664 it returns a pointer. The transport is associated with the file descriptor
 665 \fIfd\fR, which may be \fBRPC_ANYSOCK\fR, in which case a new file descriptor
 666 is created. If the file descriptor is not bound to a local \fBTCP\fR port, then
 667 this routine binds it to an arbitrary port. Refer to the \fBFile Descriptor\fR
 668 section for more information. Upon completion, \fIxprt\fR->\fBxp_fd\fR is the
 669 transport's file descriptor, and \fIxprt\fR->\fBxp_port\fR is the transport's
 670 port number. This routine returns \fBNULL\fR if it fails. Since \fBTCP-based\fR
 671 \fBRPC\fR uses buffered \fBI/O,\fR users may specify the size of buffers;
 672 values of \fB0\fR choose suitable defaults.
 673 .sp
 674 This routine exists for backward compatibility only. \fBsvc_create()\fR,
 675 \fBsvc_tli_create()\fR, or \fBsvc_vc_create()\fR should be used instead. See
 676 \fBrpc_svc_create\fR(3NSL).
 677 .RE
 678
 679 .sp
 680 .ne 2
 681 .na
 682 \fB\fBsvcudp_bufcreate()\fR\fR
 683 .ad
 684 .RS 30n
 685 This routine creates a \fBUDP/IP-based\fR \fBRPC\fR service transport, to which
 686 it returns a pointer. The transport is associated with the file descriptor
 687 \fIfd\fR. If \fIfd\fR is \fBRPC_ANYSOCK\fR then a new file descriptor is
 688 created. If the file descriptor is not bound to a local \fBUDP\fR port, then
 689 this routine binds it to an arbitrary port. Upon completion,
 690 \fIxprt\fR->\fBxp_fd\fR is the transport's file descriptor, and
 691 \fIxprt\fR->\fBxp_port\fR is the transport's port number. Refer to the \fBFile
 692 Descriptor\fR section for more information. This routine returns \fBNULL\fR if
 693 it fails.
 694 .sp
 695 The user specifies the maximum packet size for sending and receiving UDP-based
 696 \fBRPC\fR messages by using the \fIsendsz\fR and \fIrecvsz\fR parameters.
 697 .sp
 698 This routine exists for backward compatibility only. \fBsvc_tli_create()\fR, or
 699 \fBsvc_dg_create()\fR should be used instead. See \fBrpc_svc_create\fR(3NSL).
 700 .RE
 701
 702 .sp
 703 .ne 2
 704 .na
 705 \fB\fBsvcudp_create()\fR\fR
 706 .ad
 707 .RS 30n
 708 This routine creates a \fBUDP/IP-based\fR \fBRPC\fR service transport, to which
 709 it returns a pointer. The transport is associated with the file descriptor
 710 \fIfd\fR, which may be \fBRPC_ANYSOCK\fR, in which case a new file descriptor
 711 is created. If the file descriptor is not bound to a local \fBUDP\fR port, then
 712 this routine binds it to an arbitrary port. Upon completion,
 713 \fIxprt\fR->\fBxp_fd\fR is the transport's file descriptor, and
 714 \fIxprt\fR->\fBxp_port\fR is the transport's port number. This routine returns
 715 \fBNULL\fR if it fails.
 716 .sp
 717 Since \fBUDP-based\fR \fBRPC\fR messages can only hold up to 8 Kbytes of
 718 encoded data, this transport cannot be used for procedures that take large
 719 arguments or return huge results.
 720 .sp
 721 This routine exists for backward compatibility only. \fBsvc_create()\fR,
 722 \fBsvc_tli_create()\fR, or \fBsvc_dg_create()\fR should be used instead. See
 723 \fBrpc_svc_create\fR(3NSL).
 724 .RE
 725
 726 .sp
 727 .ne 2
 728 .na
 729 \fB\fBregisterrpc()\fR\fR
 730 .ad
 731 .RS 30n
 732 Register program \fIprognum\fR, procedure \fIprocname\fR, and version
 733 \fIversnum\fR with the \fBRPC\fR service package. If a request arrives for
 734 program \fIprognum\fR, version \fIversnum\fR, and procedure \fIprocnum\fR,
 735 \fIprocname\fR is called with a pointer to its parameter(s). \fIprocname\fR
 736 should return a pointer to its static result(s). \fIinproc\fR is used to decode
 737 the parameters while \fIoutproc\fR is used to encode the results. This routine
 738 returns \fB0\fR if the registration succeeded, \(mi1 otherwise.
 739 .sp
 740 \fBsvc_run()\fR must be called after all the services are registered.
 741 .sp
 742 This routine exists for backward compatibility only, and it is made obsolete by
 743 \fBrpc_reg()\fR.
 744 .RE
 745
 746 .sp
 747 .ne 2
 748 .na
 749 \fB\fBsvc_register()\fR\fR
 750 .ad
 751 .RS 30n
 752 Associates \fIprognum\fR and \fIversnum\fR with the service dispatch procedure,
 753 \fIdispatch\fR. If \fIprotocol\fR is \fB0\fR, the service is not registered
 754 with the \fBportmap\fR service. If \fIprotocol\fR is non-zero, then a mapping
 755 of the triple [\fIprognum\fR, \fIversnum\fR, \fIprotocol\fR] to
 756 \fIxprt\fR->\fBxp_port\fR is established with the local \fBportmap\fR service
 757 (generally \fIprotocol\fR is \fB0\fR, \fBIPPROTO_UDP\fR or \fBIPPROTO_TCP\fR).
 758 The procedure \fIdispatch\fR has the following form:
 759 .sp
 760 .in +2
 761 .nf
 762 \fBdispatch(struct svc_req *\fIrequest\fR, SVCXPRT *\fIxprt\fR);\fR
 763 .fi
 764 .in -2
 765
 766 The \fBsvc_register()\fR routine returns one if it succeeds, and \fB0\fR
 767 otherwise.
 768 .sp
 769 This routine exists for backward compatibility only. Enhanced functionality is
 770 provided by \fBsvc_reg()\fR.
 771 .RE
 772
 773 .sp
 774 .ne 2
 775 .na
 776 \fB\fBsvc_unregister()\fR\fR
 777 .ad
 778 .RS 30n
 779 Remove all mapping of the double [\fIprognum\fR, \fIversnum\fR] to dispatch
 780 routines, and of the triple [\fIprognum\fR, \fIversnum\fR, \fIall-protocols\fR]
 781 to port number from \fBportmap\fR.
 782 .sp
 783 This routine exists for backward compatibility. Enhanced functionality is
 784 provided by \fBsvc_unreg()\fR.
 785 .RE
 786
 787 .sp
 788 .ne 2
 789 .na
 790 \fB\fBxdr_authunix_parms()\fR\fR
 791 .ad
 792 .RS 30n
 793 Used for describing \fBUNIX\fR credentials. This routine is useful for users
 794 who wish to generate these credentials without using the \fBRPC\fR
 795 authentication package.
 796 .sp
 797 This routine exists for backward compatibility only, and is made obsolete by
 798 \fBxdr_authsys_parms()\fR. See \fBrpc_xdr\fR(3NSL).
 799 .RE
 800
 801 .SH ATTRIBUTES
 802 .LP
 803 See \fBattributes\fR(5) for descriptions of the following attributes:
 804 .sp
 805
 806 .sp
 807 .TS
 808 box;
 809 c | c
 810 l | l .
 811 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 812 _
 813 MT-Level        Unsafe
 814 .TE
 815
 816 .SH SEE ALSO
 817 .LP
 818 \fBkeyserv\fR(1M), \fBrpcbind\fR(1M), \fBrpcinfo\fR(1M), \fBnetdir\fR(3NSL),
 819 \fBnetdir_getbyname\fR(3NSL), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL),
 820 \fBrpc_clnt_calls\fR(3NSL), \fBrpc_clnt_create\fR(3NSL),
 821 \fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL),
 822 \fBrpc_svc_reg\fR(3NSL), \fBrpc_xdr\fR(3NSL), \fBrpcbind\fR(3NSL),
 823 \fBsecure_rpc\fR(3NSL), \fBselect\fR(3C), \fBxdr_authsys_parms\fR(3NSL),
 824 \fBlibnsl\fR(3LIB), \fBattributes\fR(5)
 825 .SH NOTES
 826 .LP
 827 These interfaces are unsafe in multithreaded applications.  Unsafe interfaces
 828 should be called only from the main thread.