aclx_scan or aclx_scanStr Subroutine

Purpose

Reads the access control information that is in nonbinary, readable text format, and converts it into ACL type-specific native format binary ACL data.

Library

Security Library (libc.a)

Syntax

#include <sys/acl.h>

int aclx_scan (acl_file, acl, acl_sz, acl_type, err_file) FILE * acl_file; void * acl; size_t * acl_sz; acl_type_t acl_type; FILE * err_file;

int aclx_scanStr (str, acl, acl_sz, acl_type) char * str; void * acl; size_t * acl_sz; acl_type_t acl_type;

Description

The aclx_scan and aclx_scanStr subroutines read the access control information from the input given in nonbinary, readable text format and return a binary ACL data in the ACL type-specific native format. The aclx_scan subroutine provides the ACL data text in the file specified by acl_file. In the case of aclx_scanStr, the ACL data text is provided in the string pointed to by str. When the err_file parameter is not Null, it points to a file to which any error messages are written out by the aclx_scan subroutine in case of syntax errors in the input ACL data. The errors can occur if the syntax of the input text data does not adhere to the required ACL type-specific data specifications.

Parameters

Item	Description
acl_file	Points to the file from which the ACL text output is read.
str	Points to the string from which the ACL text output is printed.
acl	Points to a buffer in which the binary ACL data has to be stored. The amount of memory available in this buffer is indicated by the acl_sz parameter.
acl_sz	Indicates the amount of memory, in bytes, available in the acl parameter.
acl_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.
err_file	File pointer to an error file. When this pointer is supplied, the subroutines write out any errors in the syntax/composition of the ACL input data.

Return Values

On successful completion, the aclx_scan and aclx_scanStr subroutines return a value of 0. Otherwise, -1 is returned and the errno global variable is set to indicate the error.

Error Codes

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

Note: The errors in the following list occur only because aclx_scan calls the fscanf subroutine internally. For more information about these errors, refer to the fscanf subroutine.

Item	Description
EAGAIN	The O_NONBLOCK flag is set for the file descriptor underlying the file specified by the acl_file parameter, and the process would be delayed in the write operation.
EBADF	The file descriptor underlying the file specified by the acl_file parameter is not a valid file descriptor open for writing.
EINTR	The write operation terminated because of a signal was received, and either no data was transferred or a partial transfer was not reported.
EIO	The process is a member of a background process group attempting to perform a write to its controlling terminal, the TOSTOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process has no parent process.
ENOSPC	Insufficient storage space is available.

The aclx_scanStr subroutine fails if the following is true:

Item	Description
ENOSPC	Insufficient storage space is available. This error is returned by sscanf, which is called by the aclx_scanStr subroutine internally.

The aclx_scan or aclx_scanStr subroutine fails if 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. This errno can also be returned if the text ACL given in the input/file string is not of the type specified by acl_type.