Accesses the group information in the user database.
Security Library (libc.a)
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.
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:
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):
|
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. |
Item | Description |
---|---|
Files Accessed: |
Mode | File |
---|---|
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.
These subroutines fail if the following is true:
Item | Description |
---|---|
EACCES | Access permission is denied for the data request. |
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. |