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

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