1ypclnt(3NSL) Networking Services Library Functions ypclnt(3NSL)
2
6 ypclnt, yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first,
7 yp_next, yp_all, yp_order, yp_master, yperr_string, ypprot_err - NIS
8 Version 2 client interface
9
11 cc [ -flag... ] file... -lnsl [ library...]
12 #include <rpcsvc/ypclnt.h>
13 #include <rpcsvc/yp_prot.h>
14 int yp_bind(char *indomain);
18 void yp_unbind (char *indomain);
21 int yp_get_default_domain(char **outdomain);
24 int yp_match(char *indomain, char *inmap, char *inkey, int inkeylen,
27 char *char **outval, int *outvallen);
28 int yp_first(char *indomain, char *inmap, char **outkey, int *outkeylen,
31 char **outval, int *outvallen);
32 int yp_next(char *indomain, char *inmap, char *inkey, int *inkeylen,
35 char **outkey, int *outkeylen, char **outval,
36 int *outvallen);
37 int yp_all(char *indomain, char *inmap, struct ypall_callback *incallback);
40 int yp_order(char *indomain, char *inmap, unsigned long *outorder);
43 int yp_master(char *indomain, char *inmap, char **outname);
46 char *yperr_string(int incode);
49 int ypprot_err(char *domain);
52
55 This package of functions provides an interface to NIS, Network Infor‐
56 mation Service Version 2, formerly referred to as YP. In this version
57 of SunOS, NIS version 2 is supported only for compatibility with previ‐
58 ous versions. The recommended enterprise level information service is
59 NIS+ or NIS version 3. See NIS+[22m(1). The current SunOS supports only the
60 client interface to NIS version 2. This client interface will in turn
61 be served either by an existing ypserv process running on another
62 machine on the network that has an earlier version of SunOS, or by a
63 NIS+ server running in "YP-compatibility mode". See rpc.nisd(1M). The
64 NOTES section in ypfiles(4) discusses the implications of being an NIS
65 client of an NIS+ server in YP-compatibility mode. For commands used to
66 access NIS from a client machine, see ypbind(1M), ypwhich(1),
67 ypmatch(1), and ypcat(1). The package can be loaded from the standard
68 library, /usr/lib/libnsl.so.1.
69 All input parameter names begin with in. Output parameters begin with
72 out. Output parameters of type char ** should be addresses of unini‐
73 tialized character pointers. Memory is allocated by the NIS client
74 package using malloc(3C) and can be freed by the user code if it has no
75 continuing need for it. For each outkey and outval, two extra bytes of
76 memory are allocated at the end that contain NEWLINE and null, respec‐
77 tively, but these two bytes are not reflected in outkeylen or out‐
78 vallen. The indomain and inmap strings must be non-null and null-termi‐
79 nated. String parameters that are accompanied by a count parameter may
80 not be null, but they may point to null strings, with the count parame‐
81 ter indicating this. Counted strings need not be null-terminated.
82 All functions in this package of type int return 0 if they succeed.
85 Otherwise, they return a failure code (YPERR_xxxx). Failure codes are
86 described in the ERRORS section.
87 Routines
89 yp_bind() To use the NIS name services, the client
90 process must be "bound" to an NIS server
91 that serves the appropriate domain using
92 yp_bind(). Binding need not be done explic‐
93 itly by user code. Binding is done automati‐
94 cally whenever an NIS lookup function is
95 called. The yp_bind() function can be called
96 directly for processes that make use of a
97 backup strategy , for example, a local file
98 in cases when NIS services are not avail‐
99 able. A process should call yp_unbind() when
100 it is finished using NIS in order to free up
101 resources.
102 yp_unbind() Each binding allocates or uses up one client
105 process socket descriptor. Each bound domain
106 costs one socket descriptor. However, multi‐
107 ple requests to the same domain use that
108 same descriptor. The yp_unbind() function is
109 available at the client interface for pro‐
110 cesses that explicitly manage their socket
111 descriptors while accessing multiple
112 domains. The call to yp_unbind() makes the
113 domain unbound, and frees all per-process
114 and per-node resources used to bind it.
115 If an RPC failure results upon use of a
117 binding, that domain will be unbound auto‐
118 matically. At that point, the ypclnt() layer
119 will retry a few more times or until the
120 operation succeeds, provided that
121 rpcbind(1M) and ypbind(1M) are running, and
122 either:
123 o The client process cannot bind a
125 server for the proper domain; or
126 o RPC requests to the server fail.
128 Under the following circumstances, the
131 ypclnt layer will return control to the user
132 code, with either an error or success code
133 and the results:
134 o If an error is not RPC-related.
136 o If rpcbind is not running.
138 o If ypbind is not running.
140 o If a bound ypserv process returns
142 any answer (success or failure).
143 yp_get_default_domain() NIS lookup calls require a map name and a
146 domain name, at minimum. The client process
147 should know the name of the map of interest.
148 Client processes fetch the node's default
149 domain by calling yp_get_default_domain()
150 and use the returned outdomain as the indo‐
151 main parameter to successive NIS name ser‐
152 vice calls. The domain returned is the same
153 as that returned using the SI_SRPC_DOMAIN
154 command to the sysinfo(2) system call. The
155 value returned in outdomain should not be
156 freed.
157 yp_match() The yp_match() function returns the value
160 associated with a passed key. This key must
161 be exact because no pattern matching is
162 available. yp_match() requires a full YP map
163 name, such as hosts.byname, instead of the
164 nickname hosts.
165 yp_first() The yp_first() function returns the first
168 key-value pair from the named map in the
169 named domain.
170 yp_next() The yp_next() function returns the next key-
173 value pair in a named map. The inkey parame‐
174 ter must be the outkey returned from an ini‐
175 tial call to yp_first() (to get the second
176 key-value pair) or the one returned from the
177 nth call to yp_next() (to get the nth + sec‐
178 ond key-value pair). Similarly, the inkeylen
179 parameter must be the outkeylen returned
180 from the earlier yp_first() or yp_next()
181 call.
182 The concept of first and next is particular
184 to the structure of the NIS map being pro‐
185 cessed. Retrieval order is not related to
186 either the lexical order within any original
187 (non-NIS name service) data base, or to any
188 obvious numerical sorting order on the keys,
189 values, or key-value pairs. The only order‐
190 ing guarantee is that if the yp_first()
191 function is called on a particular map, and
192 then the yp_next() function is repeatedly
193 called on the same map at the same server
194 until the call fails with a reason of
195 YPERR_NOMORE, every entry in the data base
196 is seen exactly once. Further, if the same
197 sequence of operations is performed on the
198 same map at the same server, the entries are
199 seen in the same order.
200 Under conditions of heavy server load or
202 server failure, the domain can become
203 unbound, then bound once again (perhaps to a
204 different server) while a client is running.
205 This binding can cause a break in one of the
206 enumeration rules. Specific entries may be
207 seen twice by the client, or not at all.
208 This approach protects the client from error
209 messages that would otherwise be returned in
210 the midst of the enumeration. For a better
211 solution to enumerating all entries in a
212 map, see yp_all().
213 yp_all() The yp_all() function provides a way to
216 transfer an entire map from server to client
217 in a single request using TCP (rather than
218 UDP as with other functions in this pack‐
219 age). The entire transaction takes place as
220 a single RPC request and response. The
221 yp_all() function can be used just like any
222 other NIS name service procedure to identify
223 the map in the normal manner and to supply
224 the name of a function that will be called
225 to process each key-value pair within the
226 map. The call to yp_all() returns only when
227 the transaction is completed (successfully
228 or unsuccessfully), or the foreach() func‐
229 tion decides that it does not want to see
230 any more key-value pairs.
231 The third parameter to yp_all() is:
233 struct ypall_callback *incallback {
235 int (*foreach)();
236 char *data;
237 };
238 The function foreach() is called:
240 foreach(int instatus, char *inkey,
242 int inkeylen, char *inval,
243 int invallen, char *indata);
244 The instatus parameter holds one of the
246 return status values defined in
247 <rpcsvc/yp_prot.h>, either YP_TRUE or an
248 error code. See ypprot_err(), for a function
249 that converts an NIS name service protocol
250 error code to a ypclnt layer error code.
251 The key and value parameters are somewhat
253 different than defined in the synopsis sec‐
254 tion above. First, the memory pointed to by
255 the inkey and inval parameters is private to
256 the yp_all() function, and is overwritten
257 with the arrival of each new key-value pair.
258 The foreach() function must do something
259 useful with the contents of that memory, but
260 it does not own the memory itself. Key and
261 value objects presented to the foreach()
262 function look exactly as they do in the
263 server's map. If they were not NEWLINE-ter‐
264 minated or null-terminated in the map, they
265 would not be here either.
266 The indata parameter is the contents of the
268 incallback->data element passed to yp_all().
269 The data element of the callback structure
270 can be used to share state information
271 between the foreach() function and the main‐
272 line code. Its use is optional, and no part
273 of the NIS client package inspects its con‐
274 tents; cast it to something useful, or
275 ignore it. The foreach() function is Bool‐
276 ean. It should return 0 to indicate that it
277 wants to be called again for further
278 received key-value pairs, or non-zero to
279 stop the flow of key-value pairs. If fore‐
280 ach() returns a non-zero value, it is not
281 called again. The functional value of
282 yp_all() is then 0.
283 yp_order() The yp_order() function returns the order
286 number for a map. The function is not sup‐
287 ported if the ypbind process on the client's
288 system is bound to an NIS+ server running in
289 "YP-compatibility mode".
290 yp_master() The yp_master() function returns the machine
293 name of the master NIS server for a map.
294 yperr_string() The yperr_string() function returns a
297 pointer to an error message string that is
298 null-terminated but contains no period or
299 NEWLINE.
300 ypprot_err() The ypprot_err() function takes an NIS name
303 service protocol error code as input, and
304 returns a ypclnt() layer error code, which
305 can be used as an input to yperr_string().
306
309 All integer functions return 0 if the requested operation is success‐
310 ful, or one of the following errors if the operation fails:
311 YPERR_ACCESS Access violation.
313 YPERR_BADARGS The arguments to the function are bad.
316 YPERR_BADDB The YP database is bad.
319 YPERR_BUSY The database is busy.
322 YPERR_DOMAIN Cannot bind to server on this domain.
325 YPERR_KEY No such key in map.
328 YPERR_MAP No such map in server's domain.
331 YPERR_NODOM Local domain name not set.
334 YPERR_NOMORE No more records in map database.
337 YPERR_PMAP Cannot communicate with rpcbind.
340 YPERR_RESRC Resource allocation failure.
343 YPERR_RPC RPC failure; domain has been unbound.
346 YPERR_YPBIND Cannot communicate with ypbind.
349 YPERR_YPERR Internal YP server or client error.
352 YPERR_YPSERV Cannot communicate with ypserv.
355 YPERR_VERS YP version mismatch.
358
361 /usr/lib/libnsl.so.1
362
364 See attributes(5) for descriptions of the following attributes:
365 ┌─────────────────────────────┬─────────────────────────────┐
370 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
371 ├─────────────────────────────┼─────────────────────────────┤
372 │MT-Level │Safe │
373 └─────────────────────────────┴─────────────────────────────┘
374
376 NIS+[22m(1), ypcat(1), ypmatch(1), ypwhich(1), rpc.nisd(1M), rpcbind(1M),
377 ypbind(1M), ypserv(1M), sysinfo(2), malloc(3C), ypfiles(4),
378 attributes(5)
379SunOS 5.11 23 Jan 2004 ypclnt(3NSL)