1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH RPCBIND 3NSL "Dec 27, 2013"
   7 .SH NAME
   8 rpcbind, rpcb_getmaps, rpcb_getaddr, rpcb_gettime, rpcb_rmtcall, rpcb_set,
   9 rpcb_unset \- library routines for RPC bind service
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <rpc/rpc.h>
  14 
  15 
  16 
  17 \fBstruct rpcblist *\fR\fBrpcb_getmaps\fR(\fBconst struct netconfig *\fR\fInetconf\fR,
  18      \fBconst char *\fR\fIhost\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBbool_t\fR  \fBrpcb_getaddr\fR(\fBconst rpcprog_t\fR  \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
  24      \fBconst struct netconfig *\fR\fInetconf\fR, \fBstruct netbuf *\fR\fIssvcaddr\fR,
  25      \fBconst char *\fR\fIhost\fR);
  26 .fi
  27 
  28 .LP
  29 .nf
  30 \fBbool_t\fR \fBrpcb_gettime\fR(\fBconst char *\fR\fIhost\fR, \fBtime_t *\fR\fItimep\fR);
  31 .fi
  32 
  33 .LP
  34 .nf
  35 \fBenum clnt_stat\fR \fBrpcb_rmtcall\fR(\fBconst struct netconfig *\fR\fInetconf\fR,
  36      \fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR,
  37      \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst rpcproc_t\fR \fIprocnum\fR,
  38      \fBconst xdrproc_t\fR \fIinproc\fR, \fBconst caddr_t\fR \fIin\fR,
  39      \fBconst xdrproc_t\fR \fIoutproc\fR \fBcaddr_t\fR \fIout\fR,
  40      \fBconst struct timeval\fR \fItout\fR, \fBstruct netbuf  *\fR\fIsvcaddr\fR);
  41 .fi
  42 
  43 .LP
  44 .nf
  45 \fBbool_t\fR \fBrpcb_set\fR(\fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
  46      \fBconst struct netconfig *\fR\fInetconf\fR, \fBconst struct netbuf *\fR\fIsvcaddr\fR);
  47 .fi
  48 
  49 .LP
  50 .nf
  51 \fBbool_t\fR \fBrpcb_unset\fR(\fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
  52      \fBconst struct netconfig *\fR\fInetconf\fR);
  53 .fi
  54 
  55 .SH DESCRIPTION
  56 .sp
  57 .LP
  58 These routines allow client C programs to make procedure calls to the RPC
  59 binder service. \fBrpcbind\fR maintains a list of mappings between programs and
  60 their universal addresses. See \fBrpcbind\fR(1M).
  61 .SS "Routines"
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBrpcb_getmaps()\fR\fR
  66 .ad
  67 .RS 18n
  68 An interface to the \fBrpcbind\fR service, which returns a list of the current
  69 \fBRPC\fR program-to-address mappings on  \fIhost\fR. It uses the transport
  70 specified through \fInetconf\fR to contact the remote \fBrpcbind\fR service on
  71 \fIhost\fR. This routine will return \fBNULL,\fR if the remote \fBrpcbind\fR
  72 could not be contacted.
  73 .RE
  74 
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBrpcb_getaddr()\fR\fR
  79 .ad
  80 .RS 18n
  81 An interface to the \fBrpcbind\fR service, which finds the address of the
  82 service on \fIhost\fR that is registered with program number \fIprognum\fR,
  83 version \fIversnum\fR, and speaks the transport protocol associated with
  84 \fInetconf\fR. The address found is returned in \fIsvcaddr\fR. \fIsvcaddr\fR
  85 should be preallocated. This routine returns \fBTRUE\fR if it succeeds.  A
  86 return value of \fBFALSE\fR means that the mapping does not exist or that the
  87 \fBRPC\fR system failed to contact the remote \fBrpcbind\fR service. In the
  88 latter case, the global variable \fBrpc_createerr\fR contains the \fBRPC\fR
  89 status. See \fBrpc_clnt_create\fR(3NSL).
  90 .RE
  91 
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBrpcb_gettime()\fR\fR
  96 .ad
  97 .RS 18n
  98 This routine returns the time on \fIhost\fR in \fItimep\fR. If \fIhost\fR is
  99 \fINULL\fR, \fBrpcb_gettime()\fR returns the time on its own machine. This
 100 routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR if it fails.
 101 \fBrpcb_gettime()\fR can be used to synchronize the time between the client and
 102 the remote server.   This routine is particularly useful for secure RPC.
 103 .RE
 104 
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBrpcb_rmtcall()\fR\fR
 109 .ad
 110 .RS 18n
 111 An interface to the \fBrpcbind\fR service, which instructs \fBrpcbind\fR on
 112 \fIhost\fR to make an \fBRPC\fR call on your behalf to a procedure on that
 113 host. The  \fBnetconfig\fR structure should correspond to a connectionless
 114 transport. The parameter \fB*\fR\fIsvcaddr\fR will be modified to the server's
 115 address if the procedure succeeds. See  \fBrpc_call()\fR and \fBclnt_call()\fR
 116 in \fBrpc_clnt_calls\fR(3NSL) for the definitions of other parameters.
 117 .sp
 118 This procedure should normally be used for a "ping" and nothing else. This
 119 routine allows programs to do lookup and call, all in one step.
 120 .sp
 121 Note: Even if the server is not running \fBrpcbind\fR does not return any error
 122 messages to the caller. In such a case, the caller times out.
 123 .sp
 124 Note: \fBrpcb_rmtcall()\fR is only available for connectionless transports.
 125 .RE
 126 
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBrpcb_set()\fR\fR
 131 .ad
 132 .RS 18n
 133 An interface to the \fBrpcbind\fR service, which establishes a mapping between
 134 the triple [\fIprognum\fR, \fIversnum\fR, \fInetconf\fR->\fInc_netid]\fR and
 135 \fIsvcaddr\fR on the machine's \fBrpcbind\fR service. The value of
 136 \fInc_netid\fR must correspond to a network identifier that is defined by the
 137 netconfig database. This routine returns \fBTRUE\fR if it succeeds, \fBFALSE\fR
 138 otherwise. See also \fBsvc_reg()\fR in \fBrpc_svc_calls\fR(3NSL). If there
 139 already exists such an entry with \fBrpcbind\fR, \fBrpcb_set()\fR will fail.
 140 .RE
 141 
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBrpcb_unset()\fR\fR
 146 .ad
 147 .RS 18n
 148 An interface to the \fBrpcbind\fR service, which destroys the mapping between
 149 the triple [\fIprognum\fR, \fIversnum\fR, \fInetconf\fR->\fInc_netid]\fR and
 150 the address on the machine's \fBrpcbind\fR service. If  \fInetconf\fR is
 151 \fINULL\fR, \fBrpcb_unset()\fR destroys all mapping between the triple
 152 [\fIprognum\fR, \fIversnum\fR, \fIall-transports\fR] and the addresses on the
 153 machine's \fBrpcbind\fR service. This routine returns \fBTRUE\fR if it
 154 succeeds,  \fBFALSE\fR otherwise. Only the owner of the service or the
 155 super-user can destroy the mapping. See also \fBsvc_unreg()\fR in
 156 \fBrpc_svc_calls\fR(3NSL).
 157 .RE
 158 
 159 .SH ATTRIBUTES
 160 .sp
 161 .LP
 162 See \fBattributes\fR(5) for descriptions of the following attributes:
 163 .sp
 164 
 165 .sp
 166 .TS
 167 box;
 168 c | c
 169 l | l .
 170 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 171 _
 172 MT-Level        MT-Safe
 173 .TE
 174 
 175 .SH SEE ALSO
 176 .sp
 177 .LP
 178 \fBrpcbind\fR(1M), \fBrpcinfo\fR(1M), \fBrpc_clnt_calls\fR(3NSL),
 179 \fBrpc_clnt_create\fR(3NSL), \fBrpc_svc_calls\fR(3NSL), \fBattributes\fR(5)