sec_login_newgroups(3sec)
Changes the group list for a login context
Synopsis
#include <dce/sec_login.h>
boolean32 sec_login_newgroups(
sec_login_handle_t login_context,
sec_login_flags_t flags,
unsigned32 num_local_groups,
sec_id_t local_groups[ ],
sec_login_handle_t *restricted_context,
error_status_t *status);
Parameters
Input
login_context
An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group
membership, and the process home directory. (See sec_intro(3sec) for more details about the login context.)
flags
A set of flags of type sec_login_flags_t. These contain information about how the new network credentials will be used. Currently, the only flag used is
sec_login_credentials_private, that, when set, implies that the new context is only to be used by the calling process. If this flag is not set (flags =
sec_login_no_flags), descendants of the calling process may also use the new network credentials.
num_local_groups
An unsigned 32-bit integer containing the number of local group identities to include in the new context.
local_groups[ ]
An array of sec_id_t elements. Each element contains the UUID of a local group identity to include in the new context. These identities are local to
the cell. Optionally, each element may also contain a pointer to a character string containing the name of the local group.
Output
restricted_context
An opaque handle to the login context containing the changed group list.
status
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.
Description
The sec_login_newgroups( ) routine changes the group list for the specified login context. Part of a network identity is a list of the various groups to
which a principal belongs. The groups are used to determine a user's access to various objects and services. This routine returns a new login context that contains the changed group list. To
remove the new login context when it is no longer needed, use sec_login_purge_context( ).
This operation does not need to be validated as the user identity does not change. Consequently, knowledge of the password is not needed.
Notes
Currently you can have only groups from the local cell.
Files
/usr/include/dce/sec_login.idl
The idl file from which dce/sec_login.h was derived.
Return Values
This routine returns TRUE when the new login context is successfully established.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
sec_login_s_auth_local
Operation not valid on local context.
sec_login_s_default_use
It is an error to try to certify the default context.
sec_login_s_groupset_invalid
The input list of group names is invalid. There may be groups to which the caller does not belong, or the list may contain groups that do not exist.
error_status_ok
The call was successful.
Examples
The following example illustrates use of the sec_login_newgroups( ) routine as part of a process to change the groupset:
sec_login_get_current_context(&login_context, &st);
sec_login_get_groups(login_context, &num_groups, &groups, &st);
...the group IDs have to
be converted from the returned UNIX numbers into UUIDs
(use sec_rgy_pgo_unix_num_to_id(3sec)...
for (i=0; i < num_groups; i++) {
... query
whether the user wants to discard any of the current group
memberships. Copy new groupset to the new_groups array ... }
if (
!sec_login_newgroups(sec_login_no_flags, num_new_groups,
new_groups, &login_context, &st)) {
if (st == sec_login_s_groupset_invalid)
printf("New
groupset invalid\n");
... application specific error handling ...
}
Related Information
Functions: