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.man.txt
+++ new/usr/src/man/man3nsl/getrpcbyname.3nsl.man.txt
1 1 GETRPCBYNAME(3NSL) Networking Services Library Functions GETRPCBYNAME(3NSL)
2 2
3 3
4 4
5 5 NAME
6 6 getrpcbyname, getrpcbyname_r, getrpcbynumber, getrpcbynumber_r,
7 7 getrpcent, getrpcent_r, setrpcent, endrpcent - get RPC entry
8 8
9 9 SYNOPSIS
10 10 cc [ flag ... ] file ... -lnsl [ library ... ]
11 11 #include <rpc/rpcent.h>
12 12
13 13
14 14
15 15 struct rpcent *getrpcbyname(const char *name);
16 16
17 17
18 18 struct rpcent *getrpcbyname_r(const char *name, struct rpcent *result,
19 19 char *buffer, int buflen);
20 20
21 21
22 22 struct rpcent *getrpcbynumber(const int number);
23 23
24 24
25 25 struct rpcent *getrpcbynumber_r(const int number, struct rpcent *result,
26 26 char *buffer, int buflen);
27 27
28 28
29 29 struct rpcent *getrpcent(void);
30 30
31 31
32 32 struct rpcent *getrpcent_r(struct rpcent *result, char *buffer,
33 33 int buflen);
34 34
35 35
36 36 void setrpcent(const int stayopen);
37 37
38 38
39 39 void endrpcent(void);
40 40
41 41
42 42 DESCRIPTION
43 43 These functions are used to obtain entries for RPC (Remote Procedure
44 44 Call) services. An entry may come from any of the sources for rpc
45 45 specified in the /etc/nsswitch.conf file (see nsswitch.conf(4)).
46 46
47 47
48 48 getrpcbyname() searches for an entry with the RPC service name
49 49 specified by the parameter name.
50 50
51 51
52 52 getrpcbynumber() searches for an entry with the RPC program number
53 53 number.
54 54
55 55
56 56 The functions setrpcent(), getrpcent(), and endrpcent() are used to
57 57 enumerate RPC entries from the database.
58 58
59 59
60 60 setrpcent() sets (or resets) the enumeration to the beginning of the
61 61 set of RPC entries. This function should be called before the first
62 62 call to getrpcent(). Calls to getrpcbyname() and getrpcbynumber() leave
63 63 the enumeration position in an indeterminate state. If the stayopen
64 64 flag is non-zero, the system may keep allocated resources such as open
65 65 file descriptors until a subsequent call to endrpcent().
66 66
67 67
68 68 Successive calls to getrpcent() return either successive entries or
69 69 NULL, indicating the end of the enumeration.
70 70
71 71
72 72 endrpcent() may be called to indicate that the caller expects to do no
73 73 further RPC entry retrieval operations; the system may then deallocate
74 74 resources it was using. It is still allowed, but possibly less
75 75 efficient, for the process to call more RPC entry retrieval functions
76 76 after calling endrpcent().
77 77
78 78 Reentrant Interfaces
79 79 The functions getrpcbyname(), getrpcbynumber(), and getrpcent() use
80 80 static storage that is re-used in each call, making these routines
81 81 unsafe for use in multithreaded applications.
82 82
83 83
84 84 The functions getrpcbyname_r(), getrpcbynumber_r(), and getrpcent_r()
85 85 provide reentrant interfaces for these operations.
86 86
87 87
88 88 Each reentrant interface performs the same operation as its non-
89 89 reentrant counterpart, named by removing the ``_r'' suffix. The
90 90 reentrant interfaces, however, use buffers supplied by the caller to
91 91 store returned results, and are safe for use in both single-threaded
92 92 and multithreaded applications.
93 93
94 94
95 95 Each reentrant interface takes the same parameters as its non-reentrant
96 96 counterpart, as well as the following additional parameters. The
97 97 parameter result must be a pointer to a struct rpcent structure
98 98 allocated by the caller. On successful completion, the function
99 99 returns the RPC entry in this structure. The parameter buffer must be a
100 100 pointer to a buffer supplied by the caller. This buffer is used as
101 101 storage space for the RPC entry data. All of the pointers within the
102 102 returned struct rpcent result point to data stored within this buffer
103 103 (see RETURN VALUES). The buffer must be large enough to hold all of the
104 104 data associated with the RPC entry. The parameter buflen should give
105 105 the size in bytes of the buffer indicated by buffer.
106 106
107 107
108 108 For enumeration in multithreaded applications, the position within the
109 109 enumeration is a process-wide property shared by all threads.
110 110 setrpcent() may be used in a multithreaded application but resets the
111 111 enumeration position for all threads. If multiple threads interleave
112 112 calls to getrpcent_r(), the threads will enumerate disjoint subsets of
113 113 the RPC entry database.
114 114
115 115
116 116 Like their non-reentrant counterparts, getrpcbyname_r() and
117 117 getrpcbynumber_r() leave the enumeration position in an indeterminate
118 118 state.
119 119
120 120 RETURN VALUES
121 121 RPC entries are represented by the struct rpcent structure defined in
122 122 <rpc/rpcent.h>:
123 123
124 124 struct rpcent {
125 125 char *r_name; /* name of this rpc service
126 126 char **r_aliases; /* zero-terminated list of alternate names */
127 127 int r_number; /* rpc program number */
128 128 };
129 129
130 130
131 131
132 132 The functions getrpcbyname(), getrpcbyname_r(), getrpcbynumber(), and
133 133 getrpcbynumber_r() each return a pointer to a struct rpcent if they
134 134 successfully locate the requested entry; otherwise they return NULL.
135 135
136 136
137 137 The functions getrpcent() and getrpcent_r() each return a pointer to a
138 138 struct rpcent if they successfully enumerate an entry; otherwise they
139 139 return NULL, indicating the end of the enumeration.
140 140
141 141
|
↓ open down ↓ |
141 lines elided |
↑ open up ↑ |
142 142 The functions getrpcbyname(), getrpcbynumber(), and getrpcent() use
143 143 static storage, so returned data must be copied before a subsequent
144 144 call to any of these functions if the data is to be saved.
145 145
146 146
147 147 When the pointer returned by the reentrant functions getrpcbyname_r(),
148 148 getrpcbynumber_r(), and getrpcent_r() is non-NULL, it is always equal
149 149 to the result pointer that was supplied by the caller.
150 150
151 151 ERRORS
152 - The reentrant functions getrpcyname_r(), getrpcbynumber_r() and
152 + The reentrant functions getrpcbyname_r(), getrpcbynumber_r() and
153 153 getrpcent_r() will return NULL and set errno to ERANGE if the length of
154 154 the buffer supplied by caller is not large enough to store the result.
155 155 See Intro(2) for the proper usage and interpretation of errno in
156 156 multithreaded applications.
157 157
158 158 FILES
159 159 /etc/rpc
160 160
161 161
162 162 /etc/nsswitch.conf
163 163
164 164 ATTRIBUTES
165 165 See attributes(5) for descriptions of the following attributes:
166 166
167 167
168 168
169 169
170 170 +---------------+--------------------------------------------+
171 171 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
172 172 +---------------+--------------------------------------------+
173 173 |MT-Level | See "Reentrant Interfaces" in DESCRIPTION. |
174 174 +---------------+--------------------------------------------+
175 175
176 176 SEE ALSO
177 177 rpcinfo(1M), rpc(3NSL), nsswitch.conf(4), rpc(4), attributes(5)
178 178
179 179 WARNINGS
180 180 The reentrant interfaces getrpcbyname_r(), getrpcbynumber_r(), and
181 181 getrpcent_r() are included in this release on an uncommitted basis
182 182 only, and are subject to change or removal in future minor releases.
183 183
184 184 NOTES
185 185 When compiling multithreaded applications, see Intro(3), Notes On
186 186 Multithreaded Applications, for information about the use of the
187 187 _REENTRANT flag.
188 188
189 189
190 190 Use of the enumeration interfaces getrpcent() and getrpcent_r() is
191 191 discouraged; enumeration may not be supported for all database sources.
192 192 The semantics of enumeration are discussed further in nsswitch.conf(4).
193 193
194 194
195 195
196 196 February 20, 1998 GETRPCBYNAME(3NSL)
|
↓ open down ↓ |
34 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX