getobjattrs Subroutine

Purpose

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

Library

Security Library (libc.a)

Syntax

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

Description

The getobjattrs 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 getobjattrs 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 must free this memory. The dbattr_t data structure contains the following fields:

The name of the target object attribute. The following valid object attributes for the getobjattrs subroutine are defined in the usersec.h file:

attr_name: Specifies the name.
attr_idx: This attribute is used internally by the getobjattrs subroutine.
attr_type: The type of a target attribute.
attr _flag: The result of the request is to read the target attribute. On successful completion, a value of zero is returned. Otherwise, a nonzero value is returned.
attr_un: A union that contains the returned values for the requested query.

The following table lists the different vales for attr_name attribute:

Name	Description	Type
S_DOMAINS	A list domains of the object.	SEC_LIST
S_CONFSETS	The list of domains defined in the conflict set of the object.	SEC_LIST
S_TYPE	The type of the object. Valid values are: S_DEVICE, S_FILE, S_NETPORT, S_NETINT	SEC_CHAR
S_SECFLAGS	The security flag associated with the object. The valid values are: FSF_DOM_ALL and FSF_DOM_ANY.	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:

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 Obj parameter, the only valid attribute that can be displayed in the Attributes array is the S_DOMAINS attribute. Specifying any other attribute with a domain name of ALL causes the getobjattrs subroutine to fail.

Parameters

Obj: Specifies the object name for the Attributes array to read.
Attributes: A pointer to an array of zero or more elements of the type dbattr_t. The list of domain-assigned object attributes is defined in the usersec.h header file.
Count: The number of array elements in the Attributes array.

Security

Files Accessed:

/etc/security/domains: mode: r

Return Values

If the object specified by the Obj parameter exists in the domain-assigned object database, the getobjattrs 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 object does not exist, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

If the getobjattrs subroutine returns -1, one of the following errno values is set:

EINVAL

The Obj parameter is NULL.

The Count parameter is less than zero.

The Attributes array is NULL and the Count parameter is greater than zero.

The Obj parameter is ALL but the Attributes entry contains an attribute other than S_DOMAINS.

ENOENT

The object specified in the Obj 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 getobjattrs subroutine fails to query an attribute, one of the following errors is returned to the attr_flag field of the corresponding Attributes element:

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 object 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 object.