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

NAME

6       nis_tables,   nis_list,   nis_add_entry,   nis_remove_entry,   nis_mod‐
7       ify_entry, nis_first_entry, nis_next_entry - NIS+ table functions
8

SYNOPSIS

10       cc [ flag ... ] file ... -lnsl [ library ... ]
11       #include <rpcsvc/nis.h>
12       nis_result *nis_list(nis_name name, uint_tflags,
13            int (*callback)(nis_name table_name,nis_object *object,
14            void *userdata), void *userdata);
15
16
17       nis_result *nis_add_entry(nis_name table_name, nis_object *object,
18            uint_t flags);
19
20
21       nis_result *nis_remove_entry(nis_name name, nis_object *object,
22            uint_t flags);
23
24
25       nis_result *nis_modify_entry(nis_name name, nis_object *object,
26            uint_t flags);
27
28
29       nis_result *nis_first_entry(nis_name table_name);
30
31
32       nis_result *nis_next_entry(nis_name table_name, netobj *cookie);
33
34
35       void nis_freeresult(nis_result *result);
36
37

DESCRIPTION

39       Use the  NIS+  table  functions  to  search  and  modify  NIS+  tables.
40       nis_list()   is   used  to  search  a  table  in  the  NIS+  namespace.
41       nis_first_entry() and nis_next_entry() are used to  enumerate  a  table
42       one  entry at a time. nis_add_entry(), nis_remove_entry(), and nis_mod‐
43       ify_entry() are used to change  the  information  stored  in  a  table.
44       nis_freeresult()  is  used  to  free  the  memory  associated  with the
45       nis_result structure.
46
47
48       Entries within a table are named by NIS+ indexed names. An indexed name
49       is  a  compound name that is composed of a search criteria and a simple
50       NIS+ name that identifies a table object. A search criteria is a series
51       of  column  names  and their associated values enclosed in bracket '[]'
52       characters. Indexed names have the following form:
53
54         [ colname=value, ... ], tablename
55
56
57
58       The list function, nis_list(), takes an indexed name as the  value  for
59       the  name  parameter.  Here,  the tablename should be a fully qualified
60       NIS+ name unless the EXPAND_NAME flag (described  below)  is  set.  The
61       second parameter, flags, defines how the function will respond to vari‐
62       ous conditions. The value for this parameter is  created  by  logically
63       ORing together one or more flags from the following list.
64
65       FOLLOW_LINKS     If  the  table specified in name resolves to be a LINK
66                        type object (see nis_objects(3NSL)), this flag  speci‐
67                        fies  that  the client library follow that link and do
68                        the search at that object. If this flag is not set and
69                        the  name resolves to a link, the error NIS_NOTSEARCH‐
70                        ABLE will be returned.
71
72
73       FOLLOW_PATH      This flag specifies that if the  entry  is  not  found
74                        within  this  table,  the list operation should follow
75                        the path specified in the table object. When  used  in
76                        conjunction with the ALL_RESULTS flag below, it speci‐
77                        fies that the path should be  followed  regardless  of
78                        the  result  of  the  search. When used in conjunction
79                        with the FOLLOW_LINKS flag above, named tables in  the
80                        path  that resolve to links will be followed until the
81                        table they point to is located. If a table in the path
82                        is  not  reachable because no server that serves it is
83                        available, the result of the operation will be  either
84                        a  "soft" success or a "soft" failure to indicate that
85                        not all tables in the path could  be  searched.  If  a
86                        name  in  the  path names is either an invalid or non-
87                        existent object then it is silently ignored.
88
89
90       HARD_LOOKUP      This flag specifies that the operation should continue
91                        trying  to contact a server of the named table until a
92                        definitive result is returned (such as NIS_NOTFOUND).
93
94
95       ALL_RESULTS      This flag can only be used in  conjunction  with  FOL‐
96                        LOW_PATH  and  a callback function. When specified, it
97                        forces all of the tables in the path to  be  searched.
98                        If name does not specify a search criteria (imply that
99                        all entries are to be returned), then this  flag  will
100                        cause  all  of the entries in all of the tables in the
101                        path to be returned.
102
103
104       NO_CACHE         This flag specifies that  the  client  library  should
105                        bypass  any  client object caches and get its informa‐
106                        tion directly from  either  the  master  server  or  a
107                        replica server for the named table.
108
109
110       MASTER_ONLY      This  flag  is  even stronger than NO_CACHE in that it
111                        specifies that the client library should only get  its
112                        information  from  the  master server for a particular
113                        table. This guarantees that the information will be up
114                        to  date.  However,  there  may  be severe performance
115                        penalties associated with contacting the master server
116                        directly  on  large networks. When used in conjunction
117                        with the HARD_LOOKUP flag, this will  block  the  list
118                        operation  until  the  master  server is up and avail‐
119                        able.
120
121
122       EXPAND_NAME      When specified, the client  library  will  attempt  to
123                        expand  a partially qualified name by calling nis_get‐
124                        names(), which uses the environment variable NIS_PATH.
125                        See nis_local_names(3NSL).
126
127
128       RETURN_RESULT    This  flag  is  used  to  specify  that  a copy of the
129                        returning object be returned in the nis_result  struc‐
130                        ture if the operation was successful.
131
132
133
134       The  third parameter to nis_list(), callback, is an optional pointer to
135       a function that will process the ENTRY type objects that  are  returned
136       from  the  search. If this pointer is NULL, then all entries that match
137       the search criteria are returned in the nis_result structure, otherwise
138       this function will be called once for each entry returned. When called,
139       this function should return 0 when additional objects are desired and 1
140       when it no longer wishes to see any more objects. The fourth parameter,
141       userdata, is simply passed to callback function along with the returned
142       entry object. The client can use this pointer to pass state information
143       or other relevant data that the callback function might need to process
144       the entries.
145
146
147       The nis_list() function is not MT-Safe with callbacks.
148
149
150       nis_add_entry()  will  add the  NIS+ object to the NIS+ table_name. The
151       flags parameter is used to specify the failure semantics  for  the  add
152       operation.  The  default  (flags equal 0) is to fail if the entry being
153       added already exists in the table. The ADD_OVERWRITE flag may  be  used
154       to  specify  that existing object is to be overwritten if it exists, (a
155       modify operation) or added if it does not exist. With the ADD_OVERWRITE
156       flag,  this  function  will  fail  with the error NIS_PERMISSION if the
157       existing object does not allow modify privileges to the client.
158
159
160       If the flag RETURN_RESULT has been specified, the server will return  a
161       copy of the resulting object if the operation was successful.
162
163
164       nis_remove_entry() removes the identified entry from the table or a set
165       of entries identified  by table_name. If the parameter object  is  non-
166       null,  it  is presumed to point to a cached copy of the entry. When the
167       removal is attempted, and the object that would be removed is  not  the
168       same  as the cached object pointed to by object then the operation will
169       fail with an NIS_NOTSAMEOBJ error. If an object  is  passed  with  this
170       function,  the  search  criteria  in name is optional as it can be con‐
171       structed from the values within the entry. However,  if  no  object  is
172       present,  the  search  criteria must be included in the name parameter.
173       If the flags variable is  null,  and  the  search  criteria   does  not
174       uniquely identify an entry, the NIS_NOTUNIQUE error is returned and the
175       operation is aborted. If the flag parameter REM_MULTIPLE is passed, and
176       if  remove  permission  is  allowed for each of these objects, then all
177       objects that match the search criteria will be  removed.  Note  that  a
178       null  search criteria and the REM_MULTIPLE flag will remove all entries
179       in a table.
180
181
182       nis_modify_entry() modifies an object identified by name. The parameter
183       object  should point to an entry with the  EN_MODIFIED flag set in each
184       column that contains new information.
185
186
187       The owner, group, and access rights of an entry are modified by placing
188       the  modified  information into the respective fields of the parameter,
189       object: zo_owner, zo_group, and zo_access.
190
191
192       These columns will replace their counterparts  in  the  entry  that  is
193       stored in the table. The entry passed must have the same number of col‐
194       umns, same type, and valid data in the modified columns for this opera‐
195       tion  to succeed.
196
197
198       If  the  flags  parameter contains the flag MOD_SAMEOBJ then the object
199       pointed to by object is assumed to be a  cached copy  of  the  original
200       object.  If  the  OID of the object passed is different than the OID of
201       the object the server  fetches,  then  the  operation  fails  with  the
202       NIS_NOTSAMEOBJ  error. This can be used to implement a simple read-mod‐
203       ify-write protocol which will fail if the object is modified before the
204       client can write the object back.
205
206
207       If  the flag RETURN_RESULT has been specified, the server will return a
208       copy of the resulting object  if the operation was successful.
209
210
211       nis_first_entry() fetches entries from a table one at a time. This mode
212       of  operation  is  extremely  inefficient  and callbacks should be used
213       instead wherever possible. The table containing the entries of interest
214       is  identified  by  name. If a search criteria is present in name it is
215       ignored. The value of cookie within the nis_result  structure  must  be
216       copied  by  the  caller into local storage and passed as an argument to
217       nis_next_entry().
218
219
220       nis_next_entry() retrieves the "next" entry from a table  specified  by
221       table_name.  The order in which entries are returned is not guaranteed.
222       Further, should an update occur in the table between  client  calls  to
223       nis_next_entry()  there  is no guarantee that an entry that is added or
224       modified will be seen by the client. Should an entry  be  removed  from
225       the  table  that  would  have been the "next" entry returned, the error
226       NIS_CHAINBROKEN is returned instead.
227
228
229       The path used when the  flag  FOLLOW_PATH  is  specified,  is  the  one
230       present in the first table searched. The path values in tables that are
231       subsequently searched are ignored.
232
233
234       It is legal to call functions that would access  the  nameservice  from
235       within  a list callback. However, calling a function that would  itself
236       use a callback, or calling nis_list() with a  callback  from  within  a
237       list callback function is not currently supported.
238
239
240       There   are  currently  no  known  methods  for  nis_first_entry()  and
241       nis_next_entry() to get their answers from only the master server.
242
243
244       The nis_list() function is not MT-Safe with callbacks. nis_list() call‐
245       backs are serialized.  A call to nis_list() with a callback from within
246       nis_list() will deadlock.   nis_list() with a callback cannot be called
247       from  an rpc server.  See rpc_svc_calls(3NSL). Otherwise, this function
248       is MT-Safe.
249

RETURN VALUES

251       These functions return a pointer to a structure of type nis_result:
252
253         struct nis_result {
254                   nis_error status;
255                   struct {
256                        uint_t    objects_len;
257                        nis_object     *objects_val;
258                   } objects;
259                   netobj    cookie;
260                   uint32_t  zticks;
261                   uint32_t  dticks;
262                   uint32_t  aticks;
263                   uint32_t  cticks;
264                 };
265
266
267
268       The status member contains the error status of  the  the  operation.  A
269       text  message  that  describes the error can be obtained by calling the
270       function nis_sperrno(). See nis_error(3NSL).
271
272
273       The objects structure contains two members. objects_val is an array  of
274       nis_object structures; objects_len is the number of cells in the array.
275       These objects  will  be  freed  by  a  call  to  nis_freeresult().  See
276       nis_names(3NSL).  If  you  need  to keep a copy of one or more objects,
277       they can be copied with the function nis_clone_object() and freed  with
278       the function nis_destroy_object(). See nis_server(3NSL).
279
280
281       The  various  ticks contain details of where the time, in microseconds,
282       was taken during a request.  They can be used to tune one's data  orga‐
283       nization  for faster access and to compare different database implemen‐
284       tations.
285
286       zticks    The time spent in the NIS+ service itself, this count  starts
287                 when  the server receives the request and stops when it sends
288                 the reply.
289
290
291       dticks    The time spent in the database backend, this time is measured
292                 from  the  time  a  database  call  starts, until a result is
293                 returned. If the request results in  multiple  calls  to  the
294                 database,  this  is  the  sum  of all the time spent in those
295                 calls.
296
297
298       aticks    The time spent in any "accelerators" or caches. This includes
299                 the  time required to locate the server needed to resolve the
300                 request.
301
302
303       cticks    The total time spent in the request, this clock  starts  when
304                 you   enter  the  client  library  and stops when a result is
305                 returned. By subtracting the sum of the  other  ticks  values
306                 from  this value you can obtain the  local overhead of gener‐
307                 ating a NIS+ request.
308
309
310
311       Subtracting the value in dticks from the value in zticks will yield the
312       time  spent in the service code itself. Subtracting the sum of the val‐
313       ues in zticks and  aticks from the value in  cticks will yield the time
314       spent  in  the  client  library itself. Note: all of the tick times are
315       measured in microseconds.
316

ERRORS

318       The client library can return a variety of error returns  and  diagnos‐
319       tics. The more salient ones are documented below.
320
321       NIS_BADATTRIBUTE       The name of an attribute did not match up with a
322                              named column in the table, or the attribute  did
323                              not have an associated value.
324
325
326       NIS_BADNAME            The  name  passed to the function is not a legal
327                              NIS+ name.
328
329
330       NIS_BADREQUEST         A problem was detected in the request  structure
331                              passed to the client library.
332
333
334       NIS_CACHEEXPIRED       The  entry  returned  came  from an object cache
335                              that has expired. This means that  the  time  to
336                              live  value  has  gone to zero and the entry may
337                              have changed. If the flag NO_CACHE was passed to
338                              the  lookup  function  then  the lookup function
339                              will retry the operation  to  get  an  unexpired
340                              copy of the object.
341
342
343       NIS_CBERROR            An RPC error occurred on the server while it was
344                              calling back to the client. The transaction  was
345                              aborted  at  that  time  and any unsent data was
346                              discarded.
347
348
349       NIS_CBRESULTS          Even though the request was successful,  all  of
350                              the  entries  have  been  sent  to your callback
351                              function and  are  thus  not  included  in  this
352                              result.
353
354
355       NIS_FOREIGNNS          The  name could not be completely resolved. When
356                              the name passed to the function would resolve in
357                              a  namespace that is outside the NIS+ name tree,
358                              this error is returned with  a  NIS+  object  of
359                              type DIRECTORY. The returned object contains the
360                              type of namespace and contact information for  a
361                              server within that namespace.
362
363
364       NIS_INVALIDOBJ         The  object  pointed to by object is not a valid
365                              NIS+ entry object  for  the  given  table.  This
366                              could  occur  if  it  had a mismatched number of
367                              columns, or a different data type than the asso‐
368                              ciated  column in the table, for example, binary
369                              or text.
370
371
372       NIS_LINKNAMEERROR      The name passed resolved to a LINK  type  object
373                              and  the  contents  of  the object pointed to an
374                              invalid name.
375
376
377       NIS_MODFAIL            The attempted modification failed for some  rea‐
378                              son.
379
380
381       NIS_NAMEEXISTS         An  attempt  was made to add a name that already
382                              exists. To add the name, first remove the exist‐
383                              ing name and then add the new name or modify the
384                              existing named object.
385
386
387       NIS_NAMEUNREACHABLE    This soft error indicates that a server for  the
388                              desired  directory  of  the  named  table object
389                              could not be reached.  This can occur when there
390                              is   a  network  partition  or  the  server  has
391                              crashed. Attempting the operation again may suc‐
392                              ceed. See the HARD_LOOKUP flag.
393
394
395       NIS_NOCALLBACK         The  server  was  unable to contact the callback
396                              service on your machine. This results in no data
397                              being returned.
398
399
400       NIS_NOMEMORY           Generally a fatal result. It means that the ser‐
401                              vice ran out of heap space.
402
403
404       NIS_NOSUCHNAME         This hard error indicates that the named  direc‐
405                              tory  of  the  table object does not exist. This
406                              occurs when the server that should be the parent
407                              of  the  server  that serves the table, does not
408                              know about the  directory  in  which  the  table
409                              resides.
410
411
412       NIS_NOSUCHTABLE        The named table does not exist.
413
414
415       NIS_NOT_ME             A  request  was  made  to a server that does not
416                              serve the given name.  Normally  this  will  not
417                              occur, however if you are not using the built in
418                              location mechanism for servers, you may see this
419                              if your mechanism is broken.
420
421
422       NIS_NOTFOUND           No  entries in the table matched the search cri‐
423                              teria. If the search criteria was  null  (return
424                              all entries) then this result means that the ta‐
425                              ble is empty and may safely be removed by  call‐
426                              ing the nis_remove().
427
428                              If  the   FOLLOW_PATH  flag  was set, this error
429                              indicates that none of the tables  in  the  path
430                              contain entries that match the search criteria.
431
432
433       NIS_NOTMASTER          A  change  request  was  made  to  a server that
434                              serves the  name,  but  it  is  not  the  master
435                              server.  This  can occur when a directory object
436                              changes and it specifies a  new  master  server.
437                              Clients that have cached copies of the directory
438                              object in the /var/nis/NIS_SHARED_DIRCACHE  file
439                              will need to have their cache managers restarted
440                              to flush this cache. Use nis_cachemgr -i.
441
442
443       NIS_NOTSAMEOBJ         An attempt to remove an object from  the  names‐
444                              pace  was  aborted because the object that would
445                              have been removed was not the same  object  that
446                              was passed in the request.
447
448
449       NIS_NOTSEARCHABLE      The  table  name resolved to a  NIS+ object that
450                              was not searchable.
451
452
453       NIS_PARTIAL            This result is similar  to  NIS_NOTFOUND  except
454                              that it means the request succeeded but resolved
455                              to zero entries. When this  occurs,  the  server
456                              returns a copy of the table object instead of an
457                              entry so that the client may  then  process  the
458                              path or implement some other local policy.
459
460
461       NIS_RPCERROR           This  fatal  error  indicates the  RPC subsystem
462                              failed in some way. Generally there  will  be  a
463                              syslog(3C)   message  indicating  why  the   RPC
464                              request failed.
465
466
467       NIS_S_NOTFOUND         The named entry does not  exist  in  the  table,
468                              however  not  all  tables  in  the path could be
469                              searched, so the entry may exist in one of those
470                              tables.
471
472
473       NIS_S_SUCCESS          Even  though the request was successful, a table
474                              in the search path was not able to be  searched,
475                              so the result may not be the same as the one you
476                              would have  received  if  that  table  had  been
477                              accessible.
478
479
480       NIS_SUCCESS            The request was successful.
481
482
483       NIS_SYSTEMERROR        Some form of generic system error occurred while
484                              attempting the  request.  Check  the  syslog(3C)
485                              record for error messages from the server.
486
487
488       NIS_TOOMANYATTRS       The  search  criteria  passed  to the server had
489                              more attributes than the  table  had  searchable
490                              columns.
491
492
493       NIS_TRYAGAIN           The  server  connected to was too busy to handle
494                              your request. add_entry(),  remove_entry(),  and
495                              modify_entry() return this error when the master
496                              server is currently updating its internal state.
497                              It  can be returned to nis_list() when the func‐
498                              tion specifies a callback and  the  server  does
499                              not have the resources to handle callbacks.
500
501
502       NIS_TYPEMISMATCH       An attempt was made to add or modify an entry in
503                              a table, and the entry passed was of a different
504                              type than the table.
505
506

ENVIRONMENT VARIABLES

508       NIS_PATH    When  set,  this  variable  is  the  search  path  used  by
509                   nis_list() if the flag   EXPAND_NAME is set.
510
511

ATTRIBUTES

513       See attributes(5) for descriptions of the following attributes:
514
515
516
517
518       ┌─────────────────────────────┬─────────────────────────────┐
519       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
520       ├─────────────────────────────┼─────────────────────────────┤
521       │MT-Level                     │MT-Safe with exceptions      │
522       └─────────────────────────────┴─────────────────────────────┘
523

SEE ALSO

525       niscat(1),      niserror(1),       nismatch(1),       nis_cachemgr(1M),
526       nis_clone_object(3NSL),  n,  nis_destroy_object(3NSL), nis_error(3NSL),
527       nis_getnames(3NSL),       nis_local_names(3NSL),       nis_names(3NSL),
528       nis_objects(3NSL),  nis_server(3NSL),  rpc_svc_calls(3NSL), syslog(3C),
529       attributes(5)
530

WARNINGS

532       Use the flag HARD_LOOKUP carefully since it can cause  the  application
533       to block indefinitely during a network partition.
534

NOTES

536       NIS+ might not be supported in future releases of the Solaris operating
537       system. Tools to aid the migration from NIS+ to LDAP are  available  in
538       the    current   Solaris   release.   For   more   information,   visit
539       http://www.sun.com/directory/nisplus/transition.html.
540
541
542
543SunOS 5.11                        10 Nov 2005                 nis_tables(3NSL)
Impressum