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