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).