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