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

NAME

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

SYNOPSIS

11       cc [ flag ... ] file ... -lnsl [ library ... ]
12       #include <rpcsvc/nis.h>
13
14
15
16       nis_name nis_leaf_of(const nis_name name);
17
18
19       nis_name nis_name_of(const nis_name name);
20
21
22       nis_name nis_domain_of(const nis_name name);
23
24
25       nis_name *nis_getnames(const nis_name name);
26
27
28       void nis_freenames(nis_name *namelist);
29
30
31       name_pos nis_dir_cmp(const nis_name n1, const nis_name n2);
32
33
34       nis_object *nis_clone_object(const nis_object *src, nis_object *dest);
35
36
37       void nis_destroy_object(nis_object *obj);
38
39
40       void nis_print_object(const nis_object *obj);
41
42

DESCRIPTION

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
48
49       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
57
58       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
63
64       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
73
74       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
81
82       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
96
97       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
106
107       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
114
115       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
118
119       nis_leaf_of(), nis_name_of()and nis_clone_object() return their results
120       as thread-specific data in multithreaded applications.
121

ENVIRONMENT VARIABLES

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
133

ATTRIBUTES

135       See attributes(5) for descriptions of the following attributes:
136
137
138
139
140       ┌─────────────────────────────┬─────────────────────────────┐
141       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
142       ├─────────────────────────────┼─────────────────────────────┤
143       │MT-Level                     │Safe                         │
144       └─────────────────────────────┴─────────────────────────────┘
145

SEE ALSO

147       nis_names(3NSL), nis_objects(3NSL), nis_tables(3NSL), attributes(5)
148

NOTES

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.
154
155
156
157SunOS 5.11                        10 Nov 2005                   nis_subr(3NSL)
Impressum