1ypclnt(3NSL)         Networking Services Library Functions        ypclnt(3NSL)
2
3
4

NAME

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

SYNOPSIS

11       cc [ -flag... ] file... -lnsl [ library...]
12       #include <rpcsvc/ypclnt.h>
13       #include <rpcsvc/yp_prot.h>
14
15
16
17       int yp_bind(char *indomain);
18
19
20       void yp_unbind (char *indomain);
21
22
23       int yp_get_default_domain(char **outdomain);
24
25
26       int yp_match(char *indomain, char *inmap, char *inkey, int inkeylen,
27            char *char **outval, int *outvallen);
28
29
30       int yp_first(char *indomain, char *inmap, char **outkey, int *outkeylen,
31            char **outval, int *outvallen);
32
33
34       int yp_next(char *indomain, char *inmap, char *inkey, int *inkeylen,
35            char **outkey, int *outkeylen, char **outval,
36            int *outvallen);
37
38
39       int yp_all(char *indomain, char *inmap, struct ypall_callback *incallback);
40
41
42       int yp_order(char *indomain, char *inmap, unsigned long *outorder);
43
44
45       int yp_master(char *indomain, char *inmap, char **outname);
46
47
48       char *yperr_string(int incode);
49
50
51       int ypprot_err(char *domain);
52
53

DESCRIPTION

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+(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
70
71       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
83
84       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
88   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
103
104       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
116                                  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
124                                      o      The client process cannot bind  a
125                                             server for the proper domain; or
126
127                                      o      RPC requests to the server fail.
128
129
130                                  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
135                                      o      If an error is not RPC-related.
136
137                                      o      If rpcbind is not running.
138
139                                      o      If ypbind is not running.
140
141                                      o      If a bound ypserv process returns
142                                             any answer (success or failure).
143
144
145       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
158
159       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
166
167       yp_first()                 The  yp_first()  function  returns the first
168                                  key-value pair from the  named  map  in  the
169                                  named domain.
170
171
172       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
183                                  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
201                                  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
214
215       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
232                                  The third parameter to yp_all() is:
233
234                                    struct ypall_callback *incallback {
235                                         int (*foreach)();
236                                         char *data;
237                                    };
238
239                                  The function foreach() is called:
240
241                                    foreach(int instatus, char *inkey,
242                                    int inkeylen, char *inval,
243                                    int invallen, char *indata);
244
245                                  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
252                                  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
267                                  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
284
285       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
291
292       yp_master()                The yp_master() function returns the machine
293                                  name of the master NIS server for a map.
294
295
296       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
301
302       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
307

RETURN VALUES

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
312       YPERR_ACCESS     Access violation.
313
314
315       YPERR_BADARGS    The arguments to the function are bad.
316
317
318       YPERR_BADDB      The YP database is bad.
319
320
321       YPERR_BUSY       The database is busy.
322
323
324       YPERR_DOMAIN     Cannot bind to server on this domain.
325
326
327       YPERR_KEY        No such key in map.
328
329
330       YPERR_MAP        No such map in server's domain.
331
332
333       YPERR_NODOM      Local domain name not set.
334
335
336       YPERR_NOMORE     No more records in map database.
337
338
339       YPERR_PMAP       Cannot communicate with rpcbind.
340
341
342       YPERR_RESRC      Resource allocation failure.
343
344
345       YPERR_RPC        RPC failure; domain has been unbound.
346
347
348       YPERR_YPBIND     Cannot communicate with ypbind.
349
350
351       YPERR_YPERR      Internal YP server or client error.
352
353
354       YPERR_YPSERV     Cannot communicate with ypserv.
355
356
357       YPERR_VERS       YP version mismatch.
358
359

FILES

361       /usr/lib/libnsl.so.1
362

ATTRIBUTES

364       See attributes(5) for descriptions of the following attributes:
365
366
367
368
369       ┌─────────────────────────────┬─────────────────────────────┐
370       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
371       ├─────────────────────────────┼─────────────────────────────┤
372       │MT-Level                     │Safe                         │
373       └─────────────────────────────┴─────────────────────────────┘
374

SEE ALSO

376       NIS+(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)
379
380
381
382SunOS 5.11                        23 Jan 2004                     ypclnt(3NSL)
Impressum