1nis_subr(3NSL) Networking Services Library Functions nis_subr(3NSL)
2
6 nis_subr, nis_leaf_of, nis_name_of, nis_domain_of, nis_getnames,
7 nis_freenames, nis_dir_cmp, nis_clone_object, nis_destroy_object,
8 nis_print_object - NIS+ subroutines
9
11 cc [ flag ... ] file ... -lnsl [ library ... ]
12 #include <rpcsvc/nis.h>
13 nis_name nis_leaf_of(const nis_name name);
17 nis_name nis_name_of(const nis_name name);
20 nis_name nis_domain_of(const nis_name name);
23 nis_name *nis_getnames(const nis_name name);
26 void nis_freenames(nis_name *namelist);
29 name_pos nis_dir_cmp(const nis_name n1, const nis_name n2);
32 nis_object *nis_clone_object(const nis_object *src, nis_object *dest);
35 void nis_destroy_object(nis_object *obj);
38 void nis_print_object(const nis_object *obj);
41
44 These subroutines are provided to assist in the development of NIS+
45 applications. They provide several useful operations on both NIS+ names
46 and objects.
47 The first group, nis_leaf_of(), nis_domain_of(), and nis_name_of() pro‐
50 vide the functions for parsing NIS+ names. nis_leaf_of() will return
51 the first label in an NIS+ name. It takes into account the double quote
52 character `"' which can be used to protect embedded `.' (dot) charac‐
53 ters in object names. Note that the name returned will never have a
54 trailing dot character. If passed the global root directory name ".",
55 it will return the null string.
56 nis_domain_of() returns the name of the NIS+ domain in which an object
59 resides. This name will always be a fully qualified NIS+ name and ends
60 with a dot. By iteratively calling nis_leaf_of() and nis_domain_of()
61 it is possible to break a NIS+ name into its individual components.
62 nis_name_of() is used to extract the unique part of a NIS+ name. This
65 function removes from the tail portion of the name all labels that are
66 in common with the local domain. Thus if a machine were in domain
67 foo.bar.baz. and nis_name_of() were passed a name
68 bob.friends.foo.bar.baz, then nis_name_of() would return the unique
69 part, bob.friends. If the name passed to this function is not in
70 either the local domain or one of its children, this function will
71 return null.
72 nis_getnames() will return a list of candidate names for the name
75 passed in as name. If this name is not fully qualified, nis_getnames()
76 will generate a list of names using the default NIS+ directory search
77 path, or the environment variable NIS_PATH if it is set. The returned
78 array of pointers is terminated by a null pointer, and the memory asso‐
79 ciated with this array should be freed by calling nis_freenames()
80 Though nis_dir_cmp() can be used to compare any two NIS+ names, it is
83 used primarily to compare domain names. This comparison is done in a
84 case independent fashion, and the results are an enum of type
85 name_pos. When the names passed to this function are identical, the
86 function returns a value of SAME_NAME. If the name n1 is a direct
87 ancestor of name n2, then this function returns the result HIGHER_NAME.
88 Similarly, if the name n1 is a direct descendant of name n2, then this
89 function returns the result LOWER_NAME. When the name n1 is neither a
90 direct ancestor nor a direct descendant of n2, as it would be if the
91 two names were siblings in separate portions of the namespace, then
92 this function returns the result NOT_SEQUENTIAL. Finally, if either
93 name cannot be parsed as a legitimate name then this function returns
94 the value BAD_NAME.
95 The second set of functions, consisting of nis_clone_object() and
98 nis_destroy_object(), are used for manipulating objects.
99 nis_clone_object() creates an exact duplicate of the NIS+ object src.
100 If the value of dest is non-null, it creates the clone of the object
101 into this object structure and allocate the necessary memory for the
102 variable length arrays. If this parameter is null, a pointer to the
103 cloned object is returned. Refer to nis_objects(3NSL) for a description
104 of the nis_object structure.
105 nis_destroy_object() can be used to destroy an object created by
108 nis_clone_object(). This will free up all memory associated with the
109 object and free the pointer passed. If the object was cloned into an
110 array using the dest parameter to nis_clone_object(), then the object
111 cannot be freed with this function. Instead, the function
112 xdr_free(xdr_nis_object,dest) must be used.
113 nis_print_object() prints out the contents of a NIS+ object structure
116 on the standard output. Its primary use is for debugging NIS+ programs.
117 nis_leaf_of(), nis_name_of()and nis_clone_object() return their results
120 as thread-specific data in multithreaded applications.
121
123 NIS_PATH This variable overrides the default NIS+ directory search
124 path used by nis_getnames(). It contains an ordered list of
125 directories separated by ':' (colon) characters. The '$'
126 (dollar sign) character is treated specially. Directory
127 names that end in '$' have the default domain appended to
128 them, and a '$' by itself is replaced by the list of direc‐
129 tories between the default domain and the global root that
130 are at least two levels deep. The default NIS+ directory
131 search path is '$'.
132
135 See attributes(5) for descriptions of the following attributes:
136 ┌─────────────────────────────┬─────────────────────────────┐
141 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
142 ├─────────────────────────────┼─────────────────────────────┤
143 │MT-Level │Safe │
144 └─────────────────────────────┴─────────────────────────────┘
145
147 nis_names(3NSL), nis_objects(3NSL), nis_tables(3NSL), attributes(5)
148
150 NIS+ might not be supported in future releases of the Solaris operating
151 system. Tools to aid the migration from NIS+ to LDAP are available in
152 the current Solaris release. For more information, visit
153 http://www.sun.com/directory/nisplus/transition.html.
154SunOS 5.11 10 Nov 2005 nis_subr(3NSL)