getgroupattr, IDtogroup, nextgroup, or putgroupattr Subroutine

Purpose

Accesses the group information in the user database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getgroupattr (GroupAttributeValueType)
char * Group;
char * Attribute;
void * Value;
int  Type;

int putgroupattr (GroupAttributeValue, Type)
char *Group;
char *Attribute;
void *Value;
int Type;

char *IDtogroup ( GID)
gid_t GID;

char *nextgroup ( Mode Argument)
int ModeArgument;

Description

Attention: These subroutines and the setpwent and setgrent subroutines should not be used simultaneously. The results can be unpredictable.

These subroutines access group information. Because of their greater granularity and extensibility, you should use them instead of the getgrent, putgrent, getgrnam, getgrgid, setgrent, and endgrent subroutines.

The getgroupattr subroutine reads a specified attribute from the group database. If the database is not already open, the subroutine will do an implicit open for reading.

Similarly, the putgroupattr subroutine writes a specified attribute into the group database. If the database is not already open, the subroutine does an implicit open for reading and writing. Data changed by putgroupattr must be explicitly committed by calling the putgroupattr subroutine with a Type parameter specifying the SEC_COMMIT value. Until the data is committed, only get subroutine calls within the process will return the written data.

New entries in the user and group databases must first be created by invoking putgroupattr with the SEC_NEW type.

The IDtogroup subroutine translates a group ID into a group name.

The nextgroup subroutine returns the next group in a linear search of the group database. The consistency of consecutive searches depends upon the underlying storage-access mechanism and is not guaranteed by this subroutine.

The setuserdb and enduserdb subroutines should be used to open and close the user database.

Parameters

Item Description
Argument Presently unused and must be specified as null.
Attribute Specifies which attribute is read. The following possible values are defined in the usersec.h file:
S_ID
Group ID. The attribute type is SEC_INT.
S_USERS
Members of the group. The attribute type is SEC_LIST.
S_ADMS
Administrators of the group. The attribute type is SEC_LIST.
S_ADMIN
Administrative status of a group. Type: SEC_BOOL.
S_GRPEXPORT
Specifies if the DCE registry can overwrite the local group information with the DCE group information during a DCE export operation. The attribute type is SEC_BOOL.

Additional user-defined attributes may be used and will be stored in the format specified by the Type parameter.

GID Specifies the group ID to be translated into a group name.
Group Specifies the name of the group for which an attribute is to be read.
Mode Specifies the search mode. Also can be used to delimit the search to one or more user credential databases. Specifying a non-null Mode value implicitly rewinds the search. A null mode continues the search sequentially through the database. This parameter specifies one of the following values as a bit mask (defined in the usersec.h file):
S_LOCAL
The local database of groups are included in the search.
S_SYSTEM
All credentials servers for the system are searched.
Type Specifies the type of attribute expected. Valid values are defined in the usersec.h file and include:
SEC_INT
The format of the attribute is an integer. The buffer returned by the getgroupattr subroutine and the buffer supplied by the putgroupattr subroutine are defined to contain an integer.
SEC_CHAR
The format of the attribute is a null-terminated character string.
SEC_LIST
The format of the attribute is a series of concatenated strings, each null-terminated. The last string in the series is terminated by two successive null characters.
SEC_BOOL
A pointer to an integer (int *) that has been cast to a null pointer.
SEC_COMMIT
For the putgroupattr subroutine, this value specified by itself indicates that changes to the named group are committed to permanent storage. The Attribute and Value parameters are ignored. If no group is specified, changes to all modified groups are committed to permanent storage.
SEC_DELETE
The corresponding attribute is deleted from the database.
SEC_NEW
If using the putgroupattr subroutine, updates all the group database files with the new group name.
Value Specifies the address of a pointer for the getgroupattr subroutine. The getgroupattr subroutine will return the address of a buffer in the pointer. For the putgroupattr subroutine, the Value parameter specifies the address of a buffer in which the attribute is stored. See the Type parameter for more details.

Security

Item Description
Files Accessed:  
Mode File
rw /etc/group (write access for putgroupattr)
rw /etc/security/group (write access for putgroupattr)

Return Values

The getgroupattr and putgroupattr subroutines, when successfully completed, return a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

The IDtogroup and nextgroup subroutines return a character pointer to a buffer containing the requested group name, if successfully completed. Otherwise, a null pointer is returned and the errno global variable is set to indicate the error.

Error Codes

Note: All of these subroutines return errors from other subroutines.

These subroutines fail if the following is true:

Item Description
EACCES Access permission is denied for the data request.
The getgroupattr subroutine fails if the following is returned:
Item Description
EIO Failed to access remote group database.

The getgroupattr and putgroupattr subroutines fail if one or more of the following are true:

Item Description
EINVAL The Value parameter does not point to a valid buffer or to valid data for this type of attribute. Limited testing is possible and all errors may not be detected.
EINVAL The Type parameter contains more than one of the SEC_INT, SEC_BOOL, SEC_CHAR, SEC_LIST, or SEC_COMMIT attributes.
EINVAL The Type parameter specifies that an individual attribute is to be committed, and the Group parameter is null.
ENOENT The specified Group parameter does not exist or the attribute is not defined for this group.
EPERM Operation is not permitted.

The IDtogroup subroutine fails if the following is true:

Item Description
ENOENT The GID parameter could not be translated into a valid group name on the system.

The nextgroup subroutine fails if one or more of the following are true:

Item Description
EINVAL The Mode parameter is not null, and does not specify either S_LOCAL or S_SYSTEM.
EINVAL The Argument parameter is not null.
ENOENT The end of the search was reached.