| blob | 18f0d86d9333c6c0d52556996fff3cc42f13cdf5 |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH YPCLNT 3NSL "Feb 25, 2017"
8 .SH NAME
9 ypclnt, yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first, yp_next,
10 yp_all, yp_order, yp_master, yperr_string, ypprot_err \- NIS Version 2 client
11 interface
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBcc\fR [ \fB-flag\fR... ] \fIfile\fR\&.\|.\|. \fB-lnsl\fR [ \fIlibrary\fR...]
16 #include <rpcsvc/ypclnt.h>
17 #include <rpcsvc/yp_prot.h>
21 \fBint\fR \fByp_bind\fR(\fBchar *\fR\fIindomain\fR);
22 .fi
24 .LP
25 .nf
26 \fBvoid\fR \fByp_unbind\fR (\fBchar *\fR\fIindomain\fR);
27 .fi
29 .LP
30 .nf
31 \fBint\fR \fByp_get_default_domain\fR(\fBchar **\fR\fIoutdomain\fR);
32 .fi
34 .LP
35 .nf
36 \fBint\fR \fByp_match\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar *\fR\fIinkey\fR, \fBint\fR \fIinkeylen\fR,
37 \fBchar *\fR\fBchar **\fR\fIoutval\fR, \fBint *\fR\fIoutvallen\fR);
38 .fi
40 .LP
41 .nf
42 \fBint\fR \fByp_first\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar **\fR\fIoutkey\fR, \fBint *\fR\fIoutkeylen\fR,
43 \fBchar **\fR\fIoutval\fR, \fBint *\fR\fIoutvallen\fR);
44 .fi
46 .LP
47 .nf
48 \fBint\fR \fByp_next\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar *\fR\fIinkey\fR, \fBint *\fR\fIinkeylen\fR,
49 \fBchar **\fR\fIoutkey\fR, \fBint *\fR\fIoutkeylen\fR, \fBchar **\fR\fIoutval\fR,
50 \fBint *\fR\fIoutvallen\fR);
51 .fi
53 .LP
54 .nf
55 \fBint\fR \fByp_all\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBstruct ypall_callback *\fR\fIincallback\fR);
56 .fi
58 .LP
59 .nf
60 \fBint\fR \fByp_order\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBunsigned long *\fR\fIoutorder\fR);
61 .fi
63 .LP
64 .nf
65 \fBint\fR \fByp_master\fR(\fBchar *\fR\fIindomain\fR, \fBchar *\fR\fIinmap\fR, \fBchar **\fR\fIoutname\fR);
66 .fi
68 .LP
69 .nf
70 \fBchar *\fR\fByperr_string\fR(\fBint\fR \fIincode\fR);
71 .fi
73 .LP
74 .nf
75 \fBint\fR \fBypprot_err\fR(\fBchar *\fR\fIdomain\fR);
76 .fi
78 .SH DESCRIPTION
79 .LP
80 This package of functions provides an interface to \fBNIS\fR, Network
81 Information Service Version 2, formerly referred to as \fBYP\fR.
82 For commands used to access \fBNIS\fR from a
83 client machine, see \fBypbind\fR(1M), \fBypwhich\fR(1), \fBypmatch\fR(1), and
84 \fBypcat\fR(1). The package can be loaded from the standard library,
85 \fB/usr/lib/libnsl.so.1\fR.
86 .sp
87 .LP
88 All input parameter names begin with \fIin\fR. Output parameters begin with
89 \fIout\fR. Output parameters of type \fBchar **\fR should be addresses of
90 uninitialized character pointers. Memory is allocated by the NIS client package
91 using \fBmalloc\fR(3C) and can be freed by the user code if it has no
92 continuing need for it. For each \fIoutkey\fR and \fIoutval\fR, two extra bytes
93 of memory are allocated at the end that contain NEWLINE and \fInull\fR,
94 respectively, but these two bytes are not reflected in \fIoutkeylen\fR or
95 \fIoutvallen\fR. The \fIindomain\fR and \fIinmap\fR strings must be non-null
96 and null-terminated. String parameters that are accompanied by a count
97 parameter may not be \fInull\fR, but they may point to null strings, with the
98 count parameter indicating this. Counted strings need not be null-terminated.
99 .sp
100 .LP
101 All functions in this package of type \fIint\fR return \fB0\fR if they succeed.
102 Otherwise, they return a failure code (\fBYPERR_\fR\fIxxxx\fR). Failure codes
103 are described in the \fBERRORS\fR section.
104 .SS "Routines"
105 .ne 2
106 .na
107 \fB\fByp_bind()\fR\fR
108 .ad
109 .RS 27n
110 To use the NIS name services, the client process must be "bound" to an NIS
111 server that serves the appropriate domain using \fByp_bind()\fR. Binding need
112 not be done explicitly by user code. Binding is done automatically whenever an
113 NIS lookup function is called. The \fByp_bind()\fR function can be called
114 directly for processes that make use of a backup strategy , for example, a
115 local file in cases when NIS services are not available. A process should call
116 \fByp_unbind()\fR when it is finished using \fBNIS\fR in order to free up
117 resources.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fByp_unbind()\fR\fR
124 .ad
125 .RS 27n
126 Each binding allocates or uses up one client process socket descriptor. Each
127 bound domain costs one socket descriptor. However, multiple requests to the
128 same domain use that same descriptor. The \fByp_unbind()\fR function is
129 available at the client interface for processes that explicitly manage their
130 socket descriptors while accessing multiple domains. The call to
131 \fByp_unbind()\fR makes the domain \fIunbound\fR, and frees all per-process and
132 per-node resources used to bind it.
133 .sp
134 If an RPC failure results upon use of a binding, that domain will be unbound
135 automatically. At that point, the \fBypclnt()\fR layer will retry a few more
136 times or until the operation succeeds, provided that \fBrpcbind\fR(1M) and
137 \fBypbind\fR(1M) are running, and either:
138 .RS +4
139 .TP
140 .ie t \(bu
141 .el o
142 The client process cannot bind a server for the proper domain; or
143 .RE
144 .RS +4
145 .TP
146 .ie t \(bu
147 .el o
148 RPC requests to the server fail.
149 .RE
150 .sp
151 .LP
152 Under the following circumstances, the \fBypclnt\fR layer will return control
153 to the user code, with either an error or success code and the results:
154 .RS +4
155 .TP
156 .ie t \(bu
157 .el o
158 If an error is not RPC-related.
159 .RE
160 .RS +4
161 .TP
162 .ie t \(bu
163 .el o
164 If \fBrpcbind\fR is not running.
165 .RE
166 .RS +4
167 .TP
168 .ie t \(bu
169 .el o
170 If \fBypbind\fR is not running.
171 .RE
172 .RS +4
173 .TP
174 .ie t \(bu
175 .el o
176 If a bound \fBypserv\fR process returns any answer (success or failure).
177 .RE
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fByp_get_default_domain()\fR\fR
184 .ad
185 .RS 27n
186 \fBNIS\fR lookup calls require a map name and a domain name, at minimum. The
187 client process should know the name of the map of interest. Client processes
188 fetch the node's default domain by calling \fByp_get_default_domain()\fR and
189 use the returned \fIoutdomain\fR as the \fIindomain\fR parameter to successive
190 \fBNIS\fR name service calls. The domain returned is the same as that returned
191 using the \fBSI_SRPC_DOMAIN\fR command to the \fBsysinfo\fR(2) system call. The
192 value returned in \fIoutdomain\fR should not be freed.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fByp_match()\fR\fR
199 .ad
200 .RS 27n
201 The \fByp_match()\fR function returns the value associated with a passed key.
202 This key must be exact because no pattern matching is available.
203 \fByp_match()\fR requires a full YP map name, such as \fBhosts.byname\fR,
204 instead of the nickname \fBhosts\fR.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fByp_first()\fR\fR
211 .ad
212 .RS 27n
213 The \fByp_first()\fR function returns the first key-value pair from the named
214 map in the named domain.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fByp_next()\fR\fR
221 .ad
222 .RS 27n
223 The \fByp_next()\fR function returns the next key-value pair in a named map.
224 The \fIinkey\fR parameter must be the \fIoutkey\fR returned from an initial
225 call to \fByp_first()\fR (to get the second key-value pair) or the one returned
226 from the \fIn\fRth call to \fByp_next()\fR (to get the \fIn\fRth + second
227 key-value pair). Similarly, the \fIinkeylen\fR parameter must be the
228 \fIoutkeylen\fR returned from the earlier \fByp_first()\fR or \fByp_next()\fR
229 call.
230 .sp
231 The concept of first and next is particular to the structure of the NIS map
232 being processed. Retrieval order is not related to either the lexical order
233 within any original (non-NIS name service) data base, or to any obvious
234 numerical sorting order on the keys, values, or key-value pairs. The only
235 ordering guarantee is that if the \fByp_first()\fR function is called on a
236 particular map, and then the \fByp_next()\fR function is repeatedly called on
237 the same map at the same server until the call fails with a reason of
238 \fBYPERR_NOMORE\fR, every entry in the data base is seen exactly once. Further,
239 if the same sequence of operations is performed on the same map at the same
240 server, the entries are seen in the same order.
241 .sp
242 Under conditions of heavy server load or server failure, the domain can become
243 unbound, then bound once again (perhaps to a different server) while a client
244 is running. This binding can cause a break in one of the enumeration rules.
245 Specific entries may be seen twice by the client, or not at all. This approach
246 protects the client from error messages that would otherwise be returned in the
247 midst of the enumeration. For a better solution to enumerating all entries in a
248 map, see \fByp_all()\fR.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fByp_all()\fR\fR
255 .ad
256 .RS 27n
257 The \fByp_all()\fR function provides a way to transfer an entire map from
258 server to client in a single request using TCP (rather than UDP as with other
259 functions in this package). The entire transaction takes place as a single RPC
260 request and response. The \fByp_all()\fR function can be used just like any
261 other NIS name service procedure to identify the map in the normal manner and
262 to supply the name of a function that will be called to process each key-value
263 pair within the map. The call to \fByp_all()\fR returns only when the
264 transaction is completed (successfully or unsuccessfully), or the
265 \fBforeach()\fR function decides that it does not want to see any more
266 key-value pairs.
267 .sp
268 The third parameter to \fByp_all()\fR is:
269 .sp
270 .in +2
271 .nf
272 struct ypall_callback *incallback {
273 int (*foreach)(\|);
274 char *data;
275 };
276 .fi
277 .in -2
279 The function \fBforeach()\fR is called:
280 .sp
281 .in +2
282 .nf
283 foreach(int \fIinstatus\fR, char *\fIinkey\fR,
284 int \fIinkeylen\fR, char *\fIinval\fR,
285 int \fIinvallen\fR, char *\fIindata\fR);
286 .fi
287 .in -2
289 The \fIinstatus\fR parameter holds one of the return status values defined in
290 <\fBrpcsvc/yp_prot.h\fR>, either \fBYP_TRUE\fR or an error code. See
291 \fBypprot_err()\fR, for a function that converts an NIS name service protocol
292 error code to a \fBypclnt\fR layer error code.
293 .sp
294 The key and value parameters are somewhat different than defined in the
295 synopsis section above. First, the memory pointed to by the \fIinkey\fR and
296 \fIinval\fR parameters is private to the \fByp_all()\fR function, and is
297 overwritten with the arrival of each new key-value pair. The \fBforeach()\fR
298 function must do something useful with the contents of that memory, but it does
299 not own the memory itself. Key and value objects presented to the
300 \fBforeach()\fR function look exactly as they do in the server's map. If they
301 were not NEWLINE-terminated or null-terminated in the map, they would not be
302 here either.
303 .sp
304 The \fIindata\fR parameter is the contents of the \fIincallback\fR->\fIdata\fR
305 element passed to \fByp_all()\fR. The \fBdata\fR element of the callback
306 structure can be used to share state information between the \fBforeach()\fR
307 function and the mainline code. Its use is optional, and no part of the NIS
308 client package inspects its contents; cast it to something useful, or ignore
309 it. The \fBforeach()\fR function is Boolean. It should return \fB0\fR to
310 indicate that it wants to be called again for further received key-value pairs,
311 or non-zero to stop the flow of key-value pairs. If \fBforeach()\fR returns a
312 non-zero value, it is not called again. The functional value of \fByp_all()\fR
313 is then \fB0\fR.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fByp_order()\fR\fR
320 .ad
321 .RS 27n
322 The \fByp_order()\fR function returns the order number for a map.
323 .RE
325 .sp
326 .ne 2
327 .na
328 \fB\fByp_master()\fR\fR
329 .ad
330 .RS 27n
331 The \fByp_master()\fR function returns the machine name of the master NIS
332 server for a map.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fByperr_string()\fR\fR
339 .ad
340 .RS 27n
341 The \fByperr_string()\fR function returns a pointer to an error message string
342 that is null-terminated but contains no period or NEWLINE.
343 .RE
345 .sp
346 .ne 2
347 .na
348 \fB\fBypprot_err()\fR\fR
349 .ad
350 .RS 27n
351 The \fBypprot_err()\fR function takes an NIS name service protocol error code
352 as input, and returns a \fBypclnt()\fR layer error code, which can be used as
353 an input to \fByperr_string()\fR.
354 .RE
356 .SH RETURN VALUES
357 .LP
358 All integer functions return \fB0\fR if the requested operation is successful,
359 or one of the following errors if the operation fails:
360 .sp
361 .ne 2
362 .na
363 \fB\fBYPERR_ACCESS\fR\fR
364 .ad
365 .RS 17n
366 Access violation.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBYPERR_BADARGS\fR\fR
373 .ad
374 .RS 17n
375 The arguments to the function are bad.
376 .RE
378 .sp
379 .ne 2
380 .na
381 \fB\fBYPERR_BADDB\fR\fR
382 .ad
383 .RS 17n
384 The \fBYP\fR database is bad.
385 .RE
387 .sp
388 .ne 2
389 .na
390 \fB\fBYPERR_BUSY\fR\fR
391 .ad
392 .RS 17n
393 The database is busy.
394 .RE
396 .sp
397 .ne 2
398 .na
399 \fB\fBYPERR_DOMAIN\fR\fR
400 .ad
401 .RS 17n
402 Cannot bind to server on this domain.
403 .RE
405 .sp
406 .ne 2
407 .na
408 \fB\fBYPERR_KEY\fR\fR
409 .ad
410 .RS 17n
411 No such key in map.
412 .RE
414 .sp
415 .ne 2
416 .na
417 \fB\fBYPERR_MAP\fR\fR
418 .ad
419 .RS 17n
420 No such map in server's domain.
421 .RE
423 .sp
424 .ne 2
425 .na
426 \fB\fBYPERR_NODOM\fR\fR
427 .ad
428 .RS 17n
429 Local domain name not set.
430 .RE
432 .sp
433 .ne 2
434 .na
435 \fB\fBYPERR_NOMORE\fR\fR
436 .ad
437 .RS 17n
438 No more records in map database.
439 .RE
441 .sp
442 .ne 2
443 .na
444 \fB\fBYPERR_PMAP\fR\fR
445 .ad
446 .RS 17n
447 Cannot communicate with \fBrpcbind\fR.
448 .RE
450 .sp
451 .ne 2
452 .na
453 \fB\fBYPERR_RESRC\fR\fR
454 .ad
455 .RS 17n
456 Resource allocation failure.
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fBYPERR_RPC\fR\fR
463 .ad
464 .RS 17n
465 \fBRPC\fR failure; domain has been unbound.
466 .RE
468 .sp
469 .ne 2
470 .na
471 \fB\fBYPERR_YPBIND\fR\fR
472 .ad
473 .RS 17n
474 Cannot communicate with \fBypbind\fR.
475 .RE
477 .sp
478 .ne 2
479 .na
480 \fB\fBYPERR_YPERR\fR\fR
481 .ad
482 .RS 17n
483 Internal \fBYP\fR server or client error.
484 .RE
486 .sp
487 .ne 2
488 .na
489 \fB\fBYPERR_YPSERV\fR\fR
490 .ad
491 .RS 17n
492 Cannot communicate with \fBypserv\fR.
493 .RE
495 .sp
496 .ne 2
497 .na
498 \fB\fBYPERR_VERS\fR\fR
499 .ad
500 .RS 17n
501 \fBYP\fR version mismatch.
502 .RE
504 .SH FILES
505 .LP
506 \fB/usr/lib/libnsl.so.1\fR
507 .SH ATTRIBUTES
508 .LP
509 See \fBattributes\fR(5) for descriptions of the following attributes:
510 .sp
512 .sp
513 .TS
514 box;
515 c | c
516 l | l .
517 ATTRIBUTE TYPE ATTRIBUTE VALUE
518 _
519 MT-Level Safe
520 .TE
522 .SH SEE ALSO
523 .LP
524 \fBypcat\fR(1), \fBypmatch\fR(1), \fBypwhich\fR(1),
525 \fBrpcbind\fR(1M), \fBypbind\fR(1M), \fBypserv\fR(1M),
526 \fBsysinfo\fR(2), \fBmalloc\fR(3C), \fBypfiles\fR(4), \fBattributes\fR(5)