1nis_names(3NSL) Networking Services Library Functions nis_names(3NSL)
2
6 nis_names, nis_lookup, nis_add, nis_remove, nis_modify, nis_freeresult
7 - NIS+ namespace functions
8
10 cc [ flag ... ] file ... -lnsl [ library ... ]
11 #include <rpcsvc/nis.h>
12 nis_result *nis_lookup(nis_name name, uint_t flags);
16 nis_result *nis_add(nis_name name, nis_object *obj);
19 nis_result *nis_remove(nis_name name, nis_object *obj);
22 nis_result *nis_modify(nis_name name, nis_object *obj);
25 void nis_freeresult(nis_result *result);
28
31 The NIS+ namespace functions are used to locate and manipulate all NIS+
32 objects except the NIS+ entry objects. See nis_objects(3NSL). To look
33 up the NIS+ entry objects within a NIS+ table, refer to nis_subr(3NSL).
34 nis_lookup() resolves a NIS+ name and returns a copy of that object
37 from a NIS+ server. nis_add() and nis_remove() add and remove objects
38 to the NIS+ namespace, respectively. nis_modify() can change specific
39 attributes of an object that already exists in the namespace.
40 These functions should be used only with names that refer to an NIS+
43 Directory, NIS+ Table, NIS+ Group, or NIS+ Private object. If a name
44 refers to an NIS+ entry object, the functions listed in nis_subr(3NSL)
45 should be used.
46 nis_freeresult() frees all memory associated with a nis_result struc‐
49 ture. This function must be called to free the memory associated with
50 a NIS+ result. nis_lookup(), nis_add(), nis_remove(), and nis_modify()
51 all return a pointer to a nis_result() structure which must be freed
52 by calling nis_freeresult() when you have finished using it. If one or
53 more of the objects returned in the structure need to be retained, they
54 can be copied with nis_clone_object(3NSL). See nis_subr(3NSL).
55 nis_lookup() takes two parameters, the name of the object to be
58 resolved in name, and a flags parameter, flags, which is defined
59 below. The object name is expected to correspond to the syntax of a
60 non-indexed NIS+ name . See nis_tables(3NSL). The nis_lookup() function
61 is the only function from this group that can use a non-fully qualified
62 name. If the parameter name is not a fully qualified name, then the
63 flag EXPAND_NAME must be specified in the call. If this flag is not
64 specified, the function will fail with the error NIS_BADNAME.
65 The flags parameter is constructed by logically ORing zero or more
68 flags from the following list.
69 FOLLOW_LINKS When specified, the client library will ``follow''
71 links by issuing another NIS+ lookup call for the
72 object named by the link. If the linked object is
73 itself a link, then this process will iterate until the
74 either a object is found that is not a LINK type
75 object, or the library has followed 16 links.
76 HARD_LOOKUP When specified, the client library will retry the
79 lookup until it is answered by a server. Using this
80 flag will cause the library to block until at least one
81 NIS+ server is available. If the network connectivity
82 is impaired, this can be a relatively long time.
83 NO_CACHE When specified, the client library will bypass any
86 object caches and will get the object from either the
87 master NIS+ server or one of its replicas.
88 MASTER_ONLY When specified, the client library will bypass any
91 object caches and any domain replicas and fetch the
92 object from the NIS+ master server for the object's
93 domain. This insures that the object returned is up to
94 date at the cost of a possible performance degradation
95 and failure if the master server is unavailable or
96 physically distant.
97 EXPAND_NAME When specified, the client library will attempt to
100 expand a partially qualified name by calling the func‐
101 tion nis_getnames(), which uses the environment vari‐
102 able NIS_PATH. See nis_subr(3NSL).
103 The status value may be translated to ASCII text using the function
107 nis_sperrno(). See nis_error(3NSL).
108 On return, the objects array in the result will contain one and possi‐
111 bly several objects that were resolved by the request. If the FOL‐
112 LOW_LINKS flag was present, on success the function could return sev‐
113 eral entry objects if the link in question pointed within a table. If
114 an error occurred when following a link, the objects array will contain
115 a copy of the link object itself.
116 The function nis_add() will take the object obj and add it to the NIS+
119 namespace with the name name. This operation will fail if the client
120 making the request does not have the create access right for the domain
121 in which this object will be added. The parameter name must contain a
122 fully qualified NIS+ name. The object members zo_name and zo_domain
123 will be constructed from this name. This operation will fail if the
124 object already exists. This feature prevents the accidental addition of
125 objects over another object that has been added by another process.
126 The function nis_remove() will remove the object with name name from
129 the NIS+ namespace. The client making this request must have the
130 destroy access right for the domain in which this object resides. If
131 the named object is a link, the link is removed and not the object that
132 it points to. If the parameter obj is not NULL, it is assumed to point
133 to a copy of the object being removed. In this case, if the object on
134 the server does not have the same object identifier as the object being
135 passed, the operation will fail with the NIS_NOTSAMEOBJ error. This
136 feature allows the client to insure that it is removing the desired
137 object. The parameter name must contain a fully qualified NIS+ name.
138 The function nis_modify() will modify the object named by name to the
141 field values in the object pointed to by obj. This object should con‐
142 tain a copy of the object from the name space that is being modified.
143 This operation will fail with the error NIS_NOTSAMEOBJ if the object
144 identifier of the passed object does not match that of the object being
145 modified in the namespace.
146 Normally the contents of the member zo_name in the nis_object structure
149 would be constructed from the name passed in the name parameter. How‐
150 ever, if it is non-null the client library will use the name in the
151 zo_name member to perform a rename operation on the object. This name
152 must not contain any unquoted `.'(dot) characters. If these conditions
153 are not met the operation will fail and return the NIS_BADNAME error
154 code.
155 You cannot modify the name of an object if that modification would
158 cause the object to reside in a different domain.
159 You cannot modify the schema of a table object.
162 Results
164 These functions return a pointer to a structure of type nis_result:
165 struct nis_result {
167 nis_error status;
168 struct {
169 uint_t objects_len;
170 nis_object *objects_val;
171 } objects;
172 netobj cookie;
173 uint32_t zticks;
174 uint32_t dticks;
175 uint32_t aticks;
176 uint32_t cticks;
177 };
178 The status member contains the error status of the the operation. A
182 text message that describes the error can be obtained by calling the
183 function nis_sperrno(). See nis_error(3NSL).
184 The objects structure contains two members. objects_val is an array of
187 nis_object structures; objects_len is the number of cells in the array.
188 These objects will be freed by the call to nis_freeresult(). If you
189 need to keep a copy of one or more objects, they can be copied with the
190 function nis_clone_object() and freed with the function
191 nis_destroy_object(). See nis_server(3NSL). Refer to nis_objects(3NSL)
192 for a description of the nis_object structure.
193 The various ticks contain details of where the time was taken during a
196 request. They can be used to tune one's data organization for faster
197 access and to compare different database implementations.
198 zticks The time spent in the NIS+ service itself. This count starts
200 when the server receives the request and stops when it sends
201 the reply.
202 dticks The time spent in the database backend. This time is measured
205 from the time a database call starts, until the result is
206 returned. If the request results in multiple calls to the
207 database, this is the sum of all the time spent in those
208 calls.
209 aticks The time spent in any ``accelerators'' or caches. This
212 includes the time required to locate the server needed to
213 resolve the request.
214 cticks The total time spent in the request. This clock starts when
217 you enter the client library and stops when a result is
218 returned. By subtracting the sum of the other ticks values
219 from this value, you can obtain the local overhead of gener‐
220 ating a NIS+ request.
221 Subtracting the value in dticks from the value in zticks will yield the
225 time spent in the service code itself. Subtracting the sum of the val‐
226 ues in zticks and aticks from the value in cticks will yield the time
227 spent in the client library itself. Note: all of the tick times are
228 measured in microseconds.
229
231 The client library can return a variety of error returns and diagnos‐
232 tics. The more salient ones are documented below.
233 NIS_SUCCESS The request was successful.
235 NIS_S_SUCCESS The request was successful, however the object
238 returned came from an object cache and not
239 directly from the server. If you do not wish to
240 see objects from object caches you must specify
241 the flag NO_CACHE when you call the lookup
242 function.
243 NIS_NOTFOUND The named object does not exist in the names‐
246 pace.
247 NIS_CACHEEXPIRED The object returned came from an object cache
250 taht has expired. The time to live value has
251 gone to zero and the object may have changed. If
252 the flag NO_CACHE was passed to the lookup func‐
253 tion then the lookup function will retry the
254 operation to get an unexpired copy of the
255 object.
256 NIS_NAMEUNREACHABLE A server for the directory of the named object
259 could not be reached. This can occur when there
260 is a network partition or all servers have
261 crashed. See the HARD_LOOKUP flag.
262 NIS_UNKNOWNOBJ The object returned is of an unknown type.
265 NIS_TRYAGAIN The server connected to was too busy to handle
268 your request. For the add, remove, and modify
269 operations this is returned when either the mas‐
270 ter server for a directory is unavailable, or
271 it is in the process of checkpointing its data‐
272 base. It can also be returned when the server is
273 updating its internal state. In the case of
274 nis_list(), NIS_TRYAGAIN is returned if the
275 client specifies a callback and the server does
276 not have enough resources to handle the call‐
277 back.
278 NIS_SYSTEMERROR A generic system error occurred while attempting
281 the request. Most commonly the server has
282 crashed or the database has become corrupted.
283 Check the syslog record for error messages from
284 the server.
285 NIS_NOT_ME A request was made to a server that does not
288 serve the name in question. Normally this will
289 not occur, however if you are not using the
290 built in location mechanism for servers you may
291 see this if your mechanism is broken.
292 NIS_NOMEMORY Generally a fatal result. It means that the
295 service ran out of heap space.
296 NIS_NAMEEXISTS An attempt was made to add a name that already
299 exists. To add the name, first remove the exist‐
300 ing name and then add the new object or modify
301 the existing named object.
302 NIS_NOTMASTER An attempt was made to update the database on a
305 replica server.
306 NIS_INVALIDOBJ The object pointed to by obj is not a valid NIS+
309 object.
310 NIS_BADNAME The name passed to the function is not a legal
313 NIS+ name.
314 NIS_LINKNAMEERROR The name passed resolved to a LINK type object
317 and the contents of the link pointed to an
318 invalid name.
319 NIS_NOTSAMEOBJ An attempt to remove an object from the names‐
322 pace was aborted because the object that would
323 have been removed was not the same object that
324 was passed in the request.
325 NIS_NOSUCHNAME This hard error indicates that the named direc‐
328 tory of the table object does not exist. This
329 occurs when the server that should be the parent
330 of the server that serves the table, does not
331 know about the directory in which the table
332 resides.
333 NIS_NOSUCHTABLE The named table does not exist.
336 NIS_MODFAIL The attempted modification failed.
339 NIS_FOREIGNNS The name could not be completely resolved. When
342 the name passed to the function would resolve in
343 a namespace that is outside the NIS+ name tree,
344 this error is returned with a NIS+ object of
345 type DIRECTORY, which contains the type of
346 namespace and contact information for a server
347 within that namespace.
348 NIS_RPCERROR This fatal error indicates the RPC subsystem
351 failed in some way. Generally there will be a
352 syslog(3C) message indicating why the RPC
353 request failed.
354
357 NIS_PATH If the flag EXPAND_NAME is set, this variable is the search
358 path used by nis_lookup().
359
362 See attributes(5) for descriptions of the following attributes:
363 ┌─────────────────────────────┬─────────────────────────────┐
368 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
369 ├─────────────────────────────┼─────────────────────────────┤
370 │MT-Level │MT-Safe │
371 └─────────────────────────────┴─────────────────────────────┘
372
374 nis_error(3NSL), nis_objects(3NSL), nis_server(3NSL), nis_subr(3NSL),
375 nis_tables(3NSL), attributes(5)
376
378 NIS+ might not be supported in future releases of the Solaris operating
379 system. Tools to aid the migration from NIS+ to LDAP are available in
380 the current Solaris release. For more information, visit
381 http://www.sun.com/directory/nisplus/transition.html.
382SunOS 5.11 10 Nov 2005 nis_names(3NSL)