Technical Reference: Base Operating System and Extensions, Volume 1

getgroupattr, IDtogroup, nextgroup, or putgroupattr Subroutine

Purpose

Accesses the group information in the user database.

Syntax

#include <usersec.h>

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

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

char *IDtogroup ( GID) gid_t GID;

char *nextgroup ( Mode, Argument) int Mode, Argument;

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

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

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:

EACCES

Access permission is denied for the data request.

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

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 Group parameter is null or contains a pointer to a null string.
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:

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:

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.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The getuserattr (getuserattr, IDtouser, nextuser, or putuserattr Subroutine) subroutine, getuserpw (getuserpw, putuserpw, or putuserpwhist Subroutine) subroutine, setpwdb subroutine, setuserdb subroutine.

List of Security and Auditing Subroutines and Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.