1nis_groups(3NSL) Networking Services Library Functions nis_groups(3NSL)
2
3
4
6 nis_groups, nis_ismember, nis_addmember, nis_removemember, nis_create‐
7 group, nis_destroygroup, nis_verifygroup, nis_print_group_entry - NIS+
8 group manipulation functions
9
11 cc [ flag ... ] file ... -lnsl [ library ... ]
12 #include <rpcsvc/nis.h>
13
14
15
16 bool_t nis_ismember(nis_name principal, nis_name group);
17
18
19 nis_error nis_addmember(nis_name member, nis_name group);
20
21
22 nis_error nis_removemember(nis_name member, nis_name group);
23
24
25 nis_error nis_creategroup(nis_name group, uint_t flags);
26
27
28 nis_error nis_destroygroup(nis_name group);
29
30
31 void nis_print_group_entry(nis_name group);
32
33
34 nis_error nis_verifygroup(nis_name group);
35
36
38 These functions manipulate NIS+ groups. They are used by NIS+ clients
39 and servers, and are the interfaces to the group authorization object.
40
41
42 The names of NIS+ groups are syntactically similar to names of NIS+
43 objects but they occupy a separate namespace. A group named "a.b.c.d."
44 is represented by a NIS+ group object named "a.groups_dir.b.c.d."; the
45 functions described here all expect the name of the group, not the name
46 of the corresponding group object.
47
48
49 There are three types of group members:
50
51 o An explicit member is just a NIS+ principal-name, for exam‐
52 ple "wickedwitch.west.oz."
53
54 o An implicit ("domain") member, written "*.west.oz.", means
55 that all principals in the given domain belong to this mem‐
56 ber. No other forms of wildcarding are allowed: "wicked‐
57 witch.*.oz." is invalid, as is "wickedwitch.west.*.". Note
58 that principals in subdomains of the given domain are not
59 included.
60
61 o A recursive ("group") member, written "@cowards.oz.", refers
62 to another group. All principals that belong to that group
63 are considered to belong here.
64
65
66 Any member may be made negative by prefixing it with a minus sign
67 ('−'). A group may thus contain explicit, implicit, recursive, nega‐
68 tive explicit, negative implicit, and negative recursive members.
69
70
71 A principal is considered to belong to a group if it belongs to at
72 least one non-negative group member of the group and belongs to no neg‐
73 ative group members.
74
75
76 The nis_ismember() function returns TRUE if it can establish that
77 principal belongs to group; otherwise it returns FALSE.
78
79
80 The nis_addmember() and nis_removemember() functions add or remove a
81 member. They do not check whether the member is valid. The user must
82 have read and modify rights for the group in question.
83
84
85 The nis_creategroup() and nis_destroygroup() functions create and
86 destroy group objects. The user must have create or destroy rights,
87 respectively, for the groups_dir directory in the appropriate domain.
88 The parameter flags to nis_creategroup() is currently unused and should
89 be set to zero.
90
91
92 The nis_print_group_entry() function lists a group's members on the
93 standard output.
94
95
96 The nis_verifygroup() function returns NIS_SUCCESS if the given group
97 exists, otherwise it returns an error code.
98
99
100 These functions only accept fully-qualified NIS+ names.
101
102
103 A group is represented by a NIS+ object with a variant part that is
104 defined in the group_obj structure. See nis_objects(3NSL). It contains
105 the following fields:
106
107 uint_t gr_flags; /* Interpretation Flags
108 (currently unused) */
109 struct {
110 uint_t gr_members_len;
111 nis_name *gr_members_val;
112 } gr_members; /* Array of members */
113
114
115
116 NIS+ servers and clients maintain a local cache of expanded groups to
117 enhance their performance when checking for group membership. Should
118 the membership of a group change, servers and clients with that group
119 cached will not see the change until either the group cache has
120 expired or it is explicitly flushed. A server's cache may be flushed
121 programmatically by calling the nis_servstate() function with tag
122 TAG_GCACHE and a value of 1.
123
124
125 There are currently no known methods for nis_ismember(),
126 nis_print_group_entry(), and nis_verifygroup() to get their answers
127 from only the master server.
128
130 Example 1 Simple Memberships
131
132
133 Given a group sadsouls.oz. with members tinman.oz., lion.oz., and
134 scarecrow.oz., the function call
135
136
137 bool_var = nis_ismember("lion.oz.", "sadsouls.oz.");
138
139
140
141
142 will return 1 (TRUE) and the function call
143
144
145 bool_var = nis_ismember("toto.oz.", "sadsouls.oz.");
146
147
148
149
150 will return 0 (FALSE).
151
152
153 Example 2 Implicit Memberships
154
155
156 Given a group baddies.oz., with members wickedwitch.west.oz. and
157 *.monkeys.west.oz., the function call bool_var = nis_ismem‐
158 ber("hogan.monkeys.west.oz.", "baddies.oz."); will return 1 (TRUE)
159 because any principal from the monkeys.west.oz. domain belongs to the
160 implicit group *.monkeys.west.oz., but the function call
161
162
163 bool_var = nis_ismember("hogan.big.monkeys.west.oz.", "baddies.oz.");
164
165
166
167
168 will return 0 (FALSE).
169
170
171 Example 3 Recursive Memberships
172
173
174 Given a group goodandbad.oz., with members toto.kansas, @sad‐
175 souls.oz., and @baddies.oz., and the groups sadsouls.oz. and bad‐
176 dies.oz. defined above, the function call
177
178
179 bool_var = nis_ismember("wickedwitch.west.oz.", "goodandbad.oz.");
180
181
182
183
184 will return 1 (TRUE), because wickedwitch.west.oz. is a member of the
185 baddies.oz. group which is recursively included in the goodandbad.oz.
186 group.
187
188
190 See attributes(5) for descriptions of the following attributes:
191
192
193
194
195 ┌─────────────────────────────┬─────────────────────────────┐
196 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
197 ├─────────────────────────────┼─────────────────────────────┤
198 │MT-Level │MT-Safe │
199 └─────────────────────────────┴─────────────────────────────┘
200
202 nisgrpadm(1), nis_objects(3NSL), attributes(5)
203
205 NIS+ might not be supported in future releases of the Solaris operating
206 system. Tools to aid the migration from NIS+ to LDAP are available in
207 the current Solaris release. For more information, visit
208 http://www.sun.com/directory/nisplus/transition.html.
209
210
211
212SunOS 5.11 10 Nov 2005 nis_groups(3NSL)