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