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

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