Accesses the group information in the user database.
Security Library (libc.a)
int getgroupattr (Group, Attribute, Value, Type)
char * Group;
char * Attribute;
void * Value;
int putgroupattr (Group, Attribute, Value, Type) char *Group; char *Attribute; void *Value; int Type;
char *IDtogroup ( GID)
char *nextgroup ( Mode, Argument)
int Mode, Argument;
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.
|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:
|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):|
|Type||Specifies the type of attribute expected. Valid values are defined
in the usersec.h file and include:
|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.|
|rw||/etc/group (write access for putgroupattr)|
|rw||/etc/security/group (write access for putgroupattr)|
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.
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
|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.|
These subroutines are part of Base Operating System (BOS) Runtime.
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.