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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

EXAMPLES

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

ATTRIBUTES

190       See attributes(5) for descriptions of the following attributes:
191
192
193
194
195       ┌─────────────────────────────┬─────────────────────────────┐
196ATTRIBUTE TYPE         ATTRIBUTE VALUE        
197       ├─────────────────────────────┼─────────────────────────────┤
198MT-Level                     MT-Safe                      
199       └─────────────────────────────┴─────────────────────────────┘
200

SEE ALSO

202       nisgrpadm(1), nis_objects(3NSL), attributes(5)
203

NOTES

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)
Impressum