putdomattrs Subroutine

Purpose

Modifies multiple domain attributes in the domain-assigned object database.

Library

Security Library (libc.a)

Syntax

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

Description

The putdomattrs subroutine modifies one or more attributes from the domain-assigned object database. The subroutine can be called only with an domain that already exists in the domain-assigned object database.

To create or remove domains, use the putdomattr subroutine instead. Data changed by the putdomattrs subroutine must be explicitly committed by calling the putdomattr subroutine with a Type parameter specifying SEC_COMMIT. Until the data is committed, only the getdomattr and getdomattrs subroutines within the process return the modified data. Changes that are made to the domain database do not impact security considerations until the entire database is sent to the Kernel Security Tables using the setkst command. The Attributes array contains information about each attribute that is to be updated. Each value specified in the Attributes array must be examined on a successful call to the putdomattrs subroutine to determine whether the value of the Attributes array was successfully written. The dbattr_t data structure contains the following fields:

Item	Description
attr_name	The name of the domain attribute to update.
attr_idx	This attribute is used internally by the putdomattrs subroutine.
attr_type	The type of the attribute that is being updated.
attr _flag	The result of the request to update the target attribute. On successful completion, a value of zero is returned. Otherwise, a value of nonzero value is returned. A union that contains the value to update the requested attribute with.
attr_domain	This field is ignored by the putdomattrs subroutine.

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

Name	Description	Type
S_DFLTMSG	The default domain description that is used when catalogs are not in use. A unique integer that is used to identify the domain.	SEC_CHAR
S_ID	Note: After the value is set initially, it must not be modified because it might be in use on the system.	SEC_INT
S_MSGCAT	The message catalog name that contains the domain description.	SEC_CHAR
S_MSGSET	The message catalog's set number for the domain description.	SEC_INT
S_MSGNUMBER	The message number for the domain description.	SEC_INT

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

Item	Description
au_char	A character pointer to the value that is to be written for attributes of SEC_CHAR and SEC_LIST types.
au_int	Integer value that is to be written for attributes of the SEC_INT type.
au_long	Long value that is to be written for attributes of the SEC_LONG type.
au_llong	Long long value that is to be written for attributes of the SEC_LLONG type.

Parameters

Item	Description
Dom	Specifies the domain name for which the attributes are to be updated.
Attribute	A pointer to an array of zero or more attributes 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 Attribute parameter.

Security

Files Accessed:

File	Mode
/etc/security/domains	rw

Return Values

If the domain specified by the Dom parameter exists in the domain database, the putdomattrs subroutine returns zero, even in the case when no attributes in the Attributes array are successfully updated. On successful completion, the attr_flag attribute of each value that is specified in the Attributes array must be examined to determine whether it was successfully updated. 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 or default. The Count parameter is less than zero. The Attributes array is NULL and the Count parameter is greater than zero. The Attributes array does not point to valid data for the requested attribute.
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 putdomattrs subroutine fails to update an attribute, one of the following errors is returned in the attr_flag field of the corresponding Attributes element:

Item	Description
EACCES	The invoker does not have write access to the domain database.
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 or to valid data for this type of attribute.

Item

Description

EACCES

The invoker does not have write access to the domain database.

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 or to valid data for this type of attribute.