1nis_tables(3NSL) Networking Services Library Functions nis_tables(3NSL)
2
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
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 nis_result *nis_add_entry(nis_name table_name, nis_object *object,
18 uint_t flags);
19 nis_result *nis_remove_entry(nis_name name, nis_object *object,
22 uint_t flags);
23 nis_result *nis_modify_entry(nis_name name, nis_object *object,
26 uint_t flags);
27 nis_result *nis_first_entry(nis_name table_name);
30 nis_result *nis_next_entry(nis_name table_name, netobj *cookie);
33 void nis_freeresult(nis_result *result);
36
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 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 [ colname=value, ... ], tablename
55 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 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 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 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 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 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 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 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 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 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 The nis_list() function is not MT-Safe with callbacks.
148 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 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 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 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 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 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 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 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 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 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 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 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 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 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
251 These functions return a pointer to a structure of type nis_result:
252 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 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 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 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 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 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 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 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 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
318 The client library can return a variety of error returns and diagnos‐
319 tics. The more salient ones are documented below.
320 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 NIS_BADNAME The name passed to the function is not a legal
327 NIS+ name.
328 NIS_BADREQUEST A problem was detected in the request structure
331 passed to the client library.
332 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 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 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 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 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 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 NIS_MODFAIL The attempted modification failed for some rea‐
378 son.
379 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 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 NIS_NOCALLBACK The server was unable to contact the callback
396 service on your machine. This results in no data
397 being returned.
398 NIS_NOMEMORY Generally a fatal result. It means that the ser‐
401 vice ran out of heap space.
402 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 NIS_NOSUCHTABLE The named table does not exist.
413 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 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 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 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 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 NIS_NOTSEARCHABLE The table name resolved to a NIS+ object that
450 was not searchable.
451 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 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 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 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 NIS_SUCCESS The request was successful.
481 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 NIS_TOOMANYATTRS The search criteria passed to the server had
489 more attributes than the table had searchable
490 columns.
491 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 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
508 NIS_PATH When set, this variable is the search path used by
509 nis_list() if the flag EXPAND_NAME is set.
510
513 See attributes(5) for descriptions of the following attributes:
514 ┌─────────────────────────────┬─────────────────────────────┐
519 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
520 ├─────────────────────────────┼─────────────────────────────┤
521 │MT-Level │MT-Safe with exceptions │
522 └─────────────────────────────┴─────────────────────────────┘
523
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
532 Use the flag HARD_LOOKUP carefully since it can cause the application
533 to block indefinitely during a network partition.
534
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.
540SunOS 5.11 10 Nov 2005 nis_tables(3NSL)