1 '\" te
   2 .\"  Copyright (c) 1998 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 GETRPCBYNAME 3NSL "Feb 20, 1998"
   7 .SH NAME
   8 getrpcbyname, getrpcbyname_r, getrpcbynumber, getrpcbynumber_r, getrpcent,
   9 getrpcent_r, setrpcent, endrpcent \- get RPC entry
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lnsl\fR [ \fIlibrary\fR ... ]
  14 #include <rpc/rpcent.h>
  15 
  16 
  17 
  18 \fBstruct rpcent *\fR\fBgetrpcbyname\fR(\fBconst char *\fR\fIname\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBstruct rpcent *\fR\fBgetrpcbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct rpcent *\fR\fIresult\fR,
  24      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
  25 .fi
  26 
  27 .LP
  28 .nf
  29 \fBstruct rpcent *\fR\fBgetrpcbynumber\fR(\fBconst int\fR \fInumber\fR);
  30 .fi
  31 
  32 .LP
  33 .nf
  34 \fBstruct rpcent *\fR\fBgetrpcbynumber_r\fR(\fBconst int\fR \fInumber\fR, \fBstruct rpcent *\fR\fIresult\fR,
  35      \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
  36 .fi
  37 
  38 .LP
  39 .nf
  40 \fBstruct rpcent *\fR\fBgetrpcent\fR(\fBvoid\fR);
  41 .fi
  42 
  43 .LP
  44 .nf
  45 \fBstruct rpcent *\fR\fBgetrpcent_r\fR(\fBstruct rpcent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
  46      \fBint\fR \fIbuflen\fR);
  47 .fi
  48 
  49 .LP
  50 .nf
  51 \fBvoid\fR \fBsetrpcent\fR(\fBconst int\fR \fIstayopen\fR);
  52 .fi
  53 
  54 .LP
  55 .nf
  56 \fBvoid\fR \fBendrpcent\fR(\fBvoid\fR);
  57 .fi
  58 
  59 .SH DESCRIPTION
  60 .LP
  61 These functions are used to obtain entries for RPC (Remote Procedure Call)
  62 services.  An entry may come from any of the sources for \fBrpc\fR specified in
  63 the \fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
  64 .sp
  65 .LP
  66 \fBgetrpcbyname()\fR searches for an entry with the RPC service name specified
  67 by the parameter \fIname\fR.
  68 .sp
  69 .LP
  70 \fBgetrpcbynumber()\fR searches for an entry with the RPC program number
  71 \fInumber\fR.
  72 .sp
  73 .LP
  74 The functions \fBsetrpcent()\fR, \fBgetrpcent()\fR, and \fBendrpcent()\fR are
  75 used to enumerate RPC entries from the database.
  76 .sp
  77 .LP
  78 \fBsetrpcent()\fR sets (or resets) the enumeration to the beginning of the set
  79 of RPC entries.  This function should be called before the first call to
  80 \fBgetrpcent()\fR. Calls to \fBgetrpcbyname()\fR and \fBgetrpcbynumber()\fR
  81 leave the enumeration position in an indeterminate state.   If the
  82 \fIstayopen\fR flag is non-zero, the system may keep allocated resources such
  83 as open file descriptors until a subsequent call to \fBendrpcent()\fR.
  84 .sp
  85 .LP
  86 Successive calls to \fBgetrpcent()\fR return either successive entries or
  87 \fBNULL,\fR indicating the end of the enumeration.
  88 .sp
  89 .LP
  90 \fBendrpcent()\fR may be called to indicate that the caller expects to do no
  91 further RPC entry retrieval operations; the system may then  deallocate
  92 resources it was using.  It is still allowed, but possibly less efficient, for
  93 the process to call more RPC entry retrieval functions after calling
  94 \fBendrpcent()\fR.
  95 .SS "Reentrant Interfaces"
  96 .LP
  97 The functions \fBgetrpcbyname()\fR, \fBgetrpcbynumber()\fR, and
  98 \fBgetrpcent()\fR use static storage that is re-used in each call, making these
  99 routines unsafe for use in multithreaded applications.
 100 .sp
 101 .LP
 102 The functions \fBgetrpcbyname_r()\fR, \fBgetrpcbynumber_r()\fR, and
 103 \fBgetrpcent_r()\fR provide reentrant interfaces for these operations.
 104 .sp
 105 .LP
 106 Each reentrant interface performs the same operation as its non-reentrant
 107 counterpart, named by removing the  ``\fB_r\fR'' suffix.  The reentrant
 108 interfaces, however, use buffers supplied by the caller to store returned
 109 results, and  are safe for use in both single-threaded and multithreaded
 110 applications.
 111 .sp
 112 .LP
 113 Each reentrant interface takes the same parameters as its non-reentrant
 114 counterpart, as well as the following additional parameters.  The parameter
 115 \fIresult\fR must be a pointer to a \fBstruct rpcent\fR structure allocated by
 116 the caller.  On successful completion, the function returns the RPC entry in
 117 this structure. The parameter \fIbuffer\fR must be a pointer to a buffer
 118 supplied by the caller.  This buffer is used as storage space for the RPC entry
 119 data.  All of the pointers within the returned \fBstruct rpcent\fR \fIresult\fR
 120 point to data stored within this buffer (see \fBRETURN VALUES\fR). The buffer
 121 must be large enough to hold all of the data associated with the RPC entry. The
 122 parameter \fIbuflen\fR should give the size in bytes of the buffer indicated by
 123 \fIbuffer\fR.
 124 .sp
 125 .LP
 126 For enumeration in multithreaded applications, the position within the
 127 enumeration is a process-wide property shared by all threads. \fBsetrpcent()\fR
 128 may be used in a multithreaded application but resets the enumeration position
 129 for all threads.  If multiple threads interleave calls to \fBgetrpcent_r()\fR,
 130 the threads will enumerate disjoint subsets of the RPC entry database.
 131 .sp
 132 .LP
 133 Like their non-reentrant counterparts, \fBgetrpcbyname_r()\fR and
 134 \fBgetrpcbynumber_r()\fR leave the enumeration position in an indeterminate
 135 state.
 136 .SH RETURN VALUES
 137 .LP
 138 RPC entries are represented by the \fBstruct rpcent\fR structure defined in
 139 \fB<rpc/rpcent.h>\fR:
 140 .sp
 141 .in +2
 142 .nf
 143 struct rpcent {
 144    char *r_name;       /* name of this rpc service
 145    char **r_aliases;   /* zero-terminated list of alternate names */
 146    int r_number;       /* rpc program number */
 147 };
 148 .fi
 149 .in -2
 150 
 151 .sp
 152 .LP
 153 The functions \fBgetrpcbyname()\fR, \fBgetrpcbyname_r(\|)\fR,
 154 \fBgetrpcbynumber(\|)\fR, and \fBgetrpcbynumber_r()\fR each return a pointer to
 155 a \fBstruct rpcent\fR if they successfully locate the requested entry;
 156 otherwise they return \fBNULL.\fR
 157 .sp
 158 .LP
 159 The functions \fBgetrpcent()\fR and \fBgetrpcent_r()\fR each return a pointer
 160 to a \fBstruct rpcent\fR if they successfully enumerate an entry; otherwise
 161 they return \fBNULL,\fR indicating the end of the enumeration.
 162 .sp
 163 .LP
 164 The functions \fBgetrpcbyname()\fR, \fBgetrpcbynumber()\fR, and
 165 \fBgetrpcent()\fR use static storage, so returned data must be copied before a
 166 subsequent call to any of these functions if the data is to be saved.
 167 .sp
 168 .LP
 169 When the pointer returned by the reentrant functions \fBgetrpcbyname_r()\fR,
 170 \fBgetrpcbynumber_r()\fR, and \fBgetrpcent_r()\fR is non-NULL, it is always
 171 equal to the \fIresult\fR pointer that was supplied by the caller.
 172 .SH ERRORS
 173 .LP
 174 The reentrant functions  \fBgetrpcbyname_r()\fR, \fBgetrpcbynumber_r(\|)\fR and
 175 \fBgetrpcent_r()\fR will return \fBNULL\fR and set \fBerrno\fR to \fBERANGE\fR
 176 if the length of the buffer supplied by caller is not large enough to store the
 177 result. See \fBIntro\fR(2) for the proper usage and interpretation of
 178 \fBerrno\fR in multithreaded applications.
 179 .SH FILES
 180 .LP
 181 \fB/etc/rpc\fR
 182 .sp
 183 .LP
 184 \fB/etc/nsswitch.conf\fR
 185 .SH ATTRIBUTES
 186 .LP
 187 See \fBattributes\fR(5) for descriptions of the following attributes:
 188 .sp
 189 
 190 .sp
 191 .TS
 192 box;
 193 c | c
 194 l | l .
 195 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 196 _
 197 MT-Level        T{
 198 See "Reentrant Interfaces" in \fBDESCRIPTION\fR.
 199 T}
 200 .TE
 201 
 202 .SH SEE ALSO
 203 .LP
 204 \fBrpcinfo\fR(1M), \fBrpc\fR(3NSL), \fBnsswitch.conf\fR(4), \fBrpc\fR(4),
 205 \fBattributes\fR(5)
 206 .SH WARNINGS
 207 .LP
 208 The reentrant interfaces \fBgetrpcbyname_r()\fR, \fBgetrpcbynumber_r()\fR, and
 209 \fBgetrpcent_r()\fR are included in this release on an uncommitted basis only,
 210 and are subject to change or removal in future minor releases.
 211 .SH NOTES
 212 .LP
 213 When compiling multithreaded applications, see  \fBIntro\fR(3), \fINotes On
 214 Multithreaded Applications\fR, for information about the use of the
 215 \fB_REENTRANT\fR flag.
 216 .sp
 217 .LP
 218 Use of the enumeration interfaces \fBgetrpcent()\fR and \fBgetrpcent_r()\fR is
 219 discouraged; enumeration may not be supported for all database sources.  The
 220 semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).