getdomattrs Subroutine

Purpose

Retrieves multiple domain attributes from the domain-assigned object database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>
int getdomattrs ( Dom, Attributes, Count)
char * Dom;
dbattr_t * Attributes;
int Count;

Description

The getdomattrs subroutine reads one or more attributes from the domain-assigned object database. The Attributes array contains information about each attribute that is to be read. Each element in the Attributes array must be examined upon a successful call to the getdomattrs subroutine, to determine whether the Attributes array was successfully retrieved. The attributes of the SEC_CHAR or SEC_LIST type will have their values returned to the allocated memory. The caller need to free this memory. The dbattr_t data structure contains the following fields:

Item	Description
attr_name	The name of the target domain attribute.
attr_idx	This attribute is used internally by the getdomattrs subroutine.
attr_type	The type of a target attribute.
attr _flag	The result of the request to read the target attribute. On successful completion, a value of zero is returned. Otherwise, a value of nonzero is returned.
attr_un	A union that contains the returned values for the requested query.
attr_domain	The getdomattrs subroutine ignores any input to this field. If this field is set to null, the subroutine sets this field to the name of the domain where the domain is found.

The following valid domain attributes for the getdomattrs subroutine are defined in the usersec.h file:

Name	Description	Type
S_DOMAINS	A list of all available domains on the system. It is valid only when the Dom parameter is set to the ALL variable.	SEC_LIST
S_DFLTMSG	The default domain description that is used when catalogs are not in use.	SEC_CHAR
S_ID	A unique integer that is used to identify the domain.	SEC_INT
S_MSGCAT	The message catalog name that contains the domain description.	SEC_CHAR
S_MSGSET	The message catalog set number of the domain description.	SEC_INT
S_MSGNUMBER	The message number of the domain description.	SEC_INT

The following union members correspond to the definitions of the ATTR_CHAR, ATTR_INT, ATTR_LONG and ATTR_LLONG macros in the usersec.h file:

Item	Description
au_char	Attributes of the SEC_CHAR and SEC_LIST types store a pointer to the returned value in this member when the attributes are successfully retrieved. The caller is responsible for freeing this memory.
au_int	The storage location for attributes of the SEC_INT type.
au_long	The storage location for attributes of the SEC_LONG type.
au_llong	The storage location for attributes of the SEC_LLONG type.

If ALL is specified for the Dom parameter, the only valid attribute that can be displayed in the Attribute array is the S_DOMAINS attribute. Specifying any other attribute with an domain name of ALL causes the getdomattrs subroutine to fail.

Parameters

Item	Description
Dom	Specifies the domain name for the Attributes array to read.
Attribute	A pointer to an array of zero or more elements of the dbattr_t type. The list of domain attributes is defined in the usersec.h header file.
Count	The number of array elements in the Attributes array.

Security

Files Accessed:

Item	Description
File	Mode
`/etc/security/domains`	`r`

Return Values

If the domain that is specified by the Dom parameter exists in the domain database, the getdomattrs subroutine returns the value of zero. On successful completion, the attr_flag attribute of each element in the Attributes array must be examined to determine whether it was successfully retrieved. If the specified domain does not exist, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

Item	Description
EINVAL	The Dom parameter is NULL. The Count parameter is less than zero. The Attributes array is NULL and the Count parameter is greater than zero. The Dom parameter is ALL but the Attributes entry contains an attribute other than S_DOMAINS.
ENOENT	The domain specified in the Dom parameter does not exist.
ENOMEM	Memory cannot be allocated.
EPERM	The operation is not permitted.
EACCES	Access permission is denied for the data request.

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

Item	Description
EACCES	The invoker does not have access to the attribute specified in the attr_name field.
EINVAL	The attr_name field in the Attributes entry is not a recognized domain attribute. The attr_type field in the Attributes entry contains a type that is not valid. The attr_un field in the Attributes entry does not point to a valid buffer.
ENOATTR	The attr_name field in the Attributes entry specifies a valid attribute, but no value is defined for this domain.

Item

Description

EACCES

The invoker does not have access to the attribute specified in the attr_name field.

EINVAL

The attr_name field in the Attributes entry is not a recognized domain attribute.

The attr_type field in the Attributes entry contains a type that is not valid.

The attr_un field in the Attributes entry does not point to a valid buffer.

ENOATTR

The attr_name field in the Attributes entry specifies a valid attribute, but no value is defined for this domain.