getgroupattrs Subroutine

Purpose

Retrieves multiple group attributes in the group database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getgroupattrs (GroupAttributesCount)
char * Group;
dbattr_t * Attributes;
int Count

Description

Attention: Do not use this subroutine and the setpwent and setgrent subroutines simultaneously. The results can be unpredictable.

The getgroupattrs subroutine accesses group information. Because of its greater granularity and extensibility, use it instead of the getgrent routines.

The getgroupattrs subroutine reads one or more attributes from the group database. If the database is not already open, this subroutine does an implicit open for reading. A call to the getgroupattrs subroutine with an Attributes parameter of null and Count parameter of 0 for every new group verifies that the group exists.

The Attributes array contains information about each attribute that is to be read. The dbattr_t data structure contains the following fields:
attr_name
The name of the desired attribute.
attr_idx
Used internally by the getgroupattrs subroutine.
attr_type
The type of the desired attribute. The list of attribute types is defined in the usersec.h header file.
attr_flag
The results of the request to read the desired attribute.
attr_un
A union containing the returned values. Its union members that follow correspond to the definitions of the attr_char, attr_int, attr_long, and attr_llong macros, respectively:
au_char
Attributes of type SEC_CHAR and SEC_LIST store a pointer to the returned attribute in this member when the requested attribute is successfully read. The caller is responsible for freeing this memory.
au_int
Attributes of type SEC_INT and SEC_BOOL store the value of the attribute in this member when the requested attribute is successfully read.
au_long
Attributes of type SEC_LONG store the value of the attribute in this member when the requested attribute is successfully read.
au_llong
Attributes of type SEC_LLONG store the value of the attribute in this member when the requested attribute is successfully read.
attr_domain
The authentication domain containing the attribute. The getgroupattrs subroutine is responsible for managing the memory referenced by this pointer. If attr_domain is specified for an attribute, the get request is sent only to that domain. If attr_domain is not specified (that is, set to NULL), getgroupattrs searches the domains in a predetermined order. The search starts with the local file system and continues with the domains specified in the /usr/lib/security/methods.cfg file. This search space can be restricted with the setauthdb subroutine so that only the domain specified in the setauthdb call is searched. If attr_domain is not specified, the getgroupattrs subroutine sets this field to the name of the domain from which the value is retrieved. If the request for a NULL domain was not satisfied, the request is tried from the local files using the default stanza.

Use the setuserdb and enduserdb subroutines to open and close the group database. Failure to explicitly open and close the group database can result in loss of memory and performance.

Parameters

Item Description
Group Specifies the name of the group for which the attributes are to be read.
Attributes A pointer to an array of 0 or more elements of type dbattr_t. The list of group attributes is defined in the usersec.h header file.
Count The number of array elements in Attributes. A Count parameter of 0 can be used to determine if the group exists.

Security

Files accessed:

Item Description
Mode File
rw /etc/group
rw /etc/security/group

Return Values

If Group exists, the getgroupattrs subroutine returns 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error. Each element in the Attributes array must be examined on a successful call to getgroupattrs to determine if the Attributes array entry was successfully retrieved.

Error Codes

The getgroupattrs subroutine returns an error that indicates that the group does or does not exist. Additional errors can indicate an error querying the information databases for the requested attributes.

Item Description
EINVAL The Count parameter is less than zero.
EINVAL The Attributes parameter is null and the Count parameter is greater than 0.
ENOENT The specified Group parameter does not exist.
EIO Failed to access the remote group database.

If the getgroupattrs subroutine fails to query an attribute, one or more of the following errors is returned in the attr_flag field of the corresponding Attributes element:

Item Description
EACCES The user does not have access to the attribute specified in the attr_name field.
EINVAL The attr_type field in the Attributes entry contains an invalid type.
EINVAL The attr_un field in the Attributes entry does not point to a valid buffer or to valid data for this type of attribute. Limited testing is possible and all errors might not be detected.
ENOATTR The attr_name field in the Attributes entry specifies an attribute that is not defined for this user or group.
ENOMEM Memory could not be allocated to store the return value.

Examples

The following sample test program displays the output to a call to getgroupattrs. In this example, the system has a user named foo.

	attribute name   : id 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 204
	
	attribute name   : admin 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 0
	
	attribute name   : adms 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 
	
	attribute name   : registry 
	attribute flag   : 0 
	attribute domain :  
	attribute value  : compat

 */
#include <stdio.h>
#include <usersec.h>

#define NATTR 4
#define GROUPNAME "bar"

char * ConvertToComma(char *);  /* Convert from SEC_LIST to SEC_CHAR with 
				   '\0' replaced with ',' */ 
main() {

	dbattr_t attributes[NATTR];  
	int 	i;
	int	rc;

	memset (&attributes, 0, sizeof(attributes));

	/*
	 * Fill in the attributes array with "id", "expires" and
	 * "SYSTEM" attributes.
	 */

	attributes[0].attr_name = S_ID;
	attributes[0].attr_type = SEC_INT;;

	attributes[1].attr_name = S_ADMIN;
	attributes[1].attr_type = SEC_BOOL;

	attributes[2].attr_name = S_ADMS;
	attributes[2].attr_type = SEC_LIST;

	attributes[3].attr_name = S_REGISTRY;
	attributes[3].attr_type = SEC_CHAR;

	/* 
	 * Make a call to getuserattrs.
	 */
        setuserdb(S_READ);

	rc = getgroupattrs(GROUPNAME, attributes, NATTR);

        enduserdb();

	if (rc) {
		printf("getgroupattrsattrs failed ....\n");
		exit(-1);
	}

	for (i = 0; i < NATTR; i++) {
		printf("attribute name   : %s \n", attributes[i].attr_name);
		printf("attribute flag   : %d \n", attributes[i].attr_flag);

		if (attributes[i].attr_flag) {

			/*
			 * No attribute value. Continue.
			 */
			printf("\n");
			continue;
		}
		/*
		 * We have a value.
		 */
		printf("attribute domain : %s \n", attributes[i].attr_domain);
		printf("attribute value  : ");

		switch (attributes[i].attr_type)
		{
			case SEC_CHAR:
				if (attributes[i].attr_char) {
                               		printf("%s\n", attributes[i].attr_char);
					free(attributes[i].attr_char);
				}
				break;
			case SEC_LIST:
				if (attributes[i].attr_char) {
                               		printf("%s\n", ConvertToComma(
						      attributes[i].attr_char));
					free(attributes[i].attr_char);
				}
                               	break;
			case SEC_INT:
			case SEC_BOOL:
                       		printf("%d\n", attributes[i].attr_int);
                               	break;
			default:
				break;
                }
		printf("\n");
	}
	exit(0);
}

/* 
 * ConvertToComme:
 * replaces NULLs in str with commas.
 */
char *
ConvertToComma(char *str)
{
        char *s = str;

        if (! str || ! *str)
                return(s);

        for (; *str; str++) {
                while(*(++str));
                *str = ',';
        }

        *(str-1) = 0;
        return(s);
}
The following output for the call is expected:
	attribute name   : id 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 204
	
	attribute name   : admin 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 0
	
	attribute name   : adms 
	attribute flag   : 0 
	attribute domain : files 
	attribute value  : 
	
	attribute name   : registry 
	attribute flag   : 0 
	attribute domain :  
	attribute value  : compat

Files

Item Description
/etc/group Contains group IDs.