aclx_convert Subroutine

Purpose

Converts the access control information from one ACL type to another.

Library

Security Library (libc.a)

Syntax

#include <sys/acl.h>

int aclx_convert (from_acl, from_sz, from_type, to_acl, to_sz, to_type, fs_obj_path)
void * from_acl;
size_t   from_sz;
acl_type_t   from_type;
void * to_acl;
size_t  * to_sz;
acl_type_t   to_type;
char  * fs_obj_path;

Description

The aclx_convert subroutine converts the access control information from the binary input given in from_acl of the ACL type from_type into a binary ACL of the type to_type and stores it in to_acl. Values from_type and to_type can be any ACL types supported in the system.

The ACL conversion takes place with the help of an ACL type-specific algorithm. Because the conversion is approximate, it can result in a potential loss of access control. Therefore, the user of this call must make sure that the converted ACL satisfies the required access controls. The user can manually review the access control information after the conversion for the file system object to ensure that the conversion was successful and satisfied the requirements of the intended access control.

Parameters

Item	Description
from_acl	Points to the ACL that has to be converted.
from_sz	Indicates the size of the ACL information pointed to by from_acl.
from_type	Indicates the ACL type information of the ACL. The acl_type is 64 bits in size and is unique on the system. If the given acl_type is not supported in the system, this function fails and errno is set to EINVAL. The supported ACL types are ACLX and NFS4.
to_acl	Points to a buffer in which the target binary ACL has to be stored. The amount of memory available in this buffer is indicated by the to_sz parameter.
to_sz	Indicates the amount of memory, in bytes, available in to_acl. If to_sz contains less than the required amount of memory for storing the converted ACL, to_sz is set to the required amount of memory and ENOSPC* is returned by errno.
to_type	Indicates the ACL type to which conversion needs to be done. The ACL type is 64 bits in size and is unique on the system. If the given acl_type is not supported in the system, this function fails and errno is set to EINVAL The supported ACL types are ACLX and NFS4.
fs_obj_path	File System Object Path for which the ACL conversion is being requested. Gets information about the object, such as whether it is file or directory.

Return Values

On successful completion, the aclx_convert subroutine returns a value of 0. Otherwise, -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The aclx_convert subroutine fails if one or more of the following is true:

Item	Description
EINVAL	Invalid input parameter. The same error can be returned if an invalid acl_type is specified as input to this routine, either in from_type or in to_type. This errno could also be returned if the binary ACL given in from_acl is not the type specified by from_type.
ENOSPC	Insufficient storage space is available in to_acl.

Security

Access Control: The invoker must have search permission for all components of the Path prefix.

Auditing Events: If the auditing subsystem has been properly configured and is enabled, the aclx_convert subroutine generates the following audit record (event) every time the command is executed:

Item	Description
Event	Information
FILE_Acl	Lists access controls.