acl_library(3) DG/UX B2 Security R4.12MU02 acl_library(3)
NAME
acllibrary: acladdperm, aclalloc, aclcalcmask, aclcopyentry,
aclcreateentry, acldeleteentry, acldeleteperm, aclfree,
aclfromexport, aclgetentry, aclgetperm, aclgettag,
aclpackagesize, aclread, aclrewind, aclsetperm, aclsettag,
acltoexport, aclvalid, aclwrite, aclallocated, aclclear,
aclentryvalid, aclfprintf, aclgettext, aclinternalclear,
aclinternalcopy, aclinternalfree, aclnocalcmask, aclorder,
aclprintf, aclreadject, aclwriteject - ACL routines in
libtrust.a
SYNOPSIS
The following functions are modeled after the POSIX 1003.6 Draft
ballot functions of the same name:
#include <sys/acl.h>
int acladdperm (aclentryt entryd,
aclpermsett perms)
int aclalloc (aclt *acldp)
int aclcalcmask (aclt acld)
int aclcopyentry (aclentryt srcd,
aclentryt destd)
int aclcreateentry (aclt acld,
aclentryt *entrydp)
int acldeleteentry (aclentryt entrydp)
int acldeleteperm (aclentryt entrydp,
aclpermsett perms)
int aclfree (aclt acld)
int aclfromexport (char *buf,
aclpackagetypt packtype,
aclt acld)
int aclgetentry (aclt acld,
aclentryt *entrydp)
int aclgetperm (aclentryt entryd,
aclpermsett *perms)
int aclgettag (aclentryt entryd,
acltagt *tagtype,
void *tagqualifier)
ssizet aclpackagesize (aclt acld,
aclpackagetypet packtype)
int aclread (char *path,
acltypet type,
aclt acld)
int aclrewind (aclt acld)
int aclsetperm (aclentryt entryd,
aclpermsett perms)
int aclsettag (aclentryt entryd,
acltagt tagtype,
void *tagqualifier)
ssizet acltoexport (aclt acld,
char *buf,
ssizet buflen,
aclpackagetypet packtype)
int aclvalid (aclt acld,
acltypet type,
aclentryt *entrydp)
int aclwrite (char *path,
acltypet type,
aclt acld)
The following functions are unique to systems running a DG/UX
information security option configured with access control lists.
These functions may not be portable to other systems:
#include <acl.h>
int aclallocated (aclt acld)
int aclclear (aclt acld)
int aclentryvalid (aclentryt entryd)
int aclfprintf (FILE *file,
jectjecttype jecttype,
int targtype,
const void *targ,
int acltype,
secobjectenumtype objtype,
aclt acld,
int flags,
aclpermsett *maskptr)
char *aclgettext (jectjecttype jecttype,
int targtype,
const void *targ,
int acltype,
secobjectenumtype objtype,
aclt acld,
int *lenptr,
int flags,
aclpermsett *maskptr)
int aclinternalclear (aclt acld)
int aclinternalcopy (aclt src,
aclt dest)
int aclinternalfree (aclt *acldp)
int aclnocalcmask (aclt acld)
void aclorder (aclt acld)
int aclprintf (jectjecttype jecttype,
int targtype,
const void *targ,
int acltype,
secobjectenumtype objtype,
aclt acld,
int flags,
aclpermsett *maskptr)
int aclreadject (jectjecttype jecttype,
int targtype,
const void *targ,
int acltype,
aclt acld,
int flags)
int aclwriteject (jectjecttype jecttype,
int targtype,
const void *targ,
int acltype,
aclt acld,
int flags)
DESCRIPTION
The functions in acllibrary provide support for access control lists
in DG/UX information security options. These functions can be found
in libtrust.a. Some of these functions need functions found in
libdgc.a.
The functions return 0 on success and -1 on failure unless otherwise
noted.
acladdperm
This function adds the set of permissions found in perms to the ACL
entry referred to by argument entryd. Any permissions the ACL entry
had prior to the call are left unchanged. Adding a permission that
is already granted by the entry is not an error.
Errors:
EINVAL entryd does not refer to a valid ACL entry.
EINVAL perms contains values not defined in aclpermsett.
aclalloc
This function allocates and initializes a temporary area in which an
ACL may be manipulated. acldp is set to reference the created area.
Errors:
ENOMEM Could not allocate the memory for the aclt object.
EINVAL *acldp is not a valid pointer.
aclcalcmask
This function calculates and sets the ACL_MASK_OBJ ACL entry for the
ACL indicated by acld. The value of ACL_MASK_OBJ is the union of
the permissions of all ACL entries that refer to members of the File
Group Class (i.e., ACL_GROUP_OBJ, ACL_USER, ACL_GROUP). The value of
ACL_MASK_OBJ is identical to the file group class permission bits as
displayed by the ls -l command. If the ACL acld already contains an
ACL_MASK_OBJ, its permissions are overwritten; if it does not
contain an ACL_MASK_OBJ, one is added.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
ENOMEM Can't allocate the memory required for an ACL entry.
aclcopyentry
This function copies the contents of the ACL entry srcd to the ACL
entry destd. srcd and destd may refer to entries in different
aclt structures. The previous contents of the ACL entry destd are
overwritten.
Errors:
EINVAL srcd or destd does not refer to a valid ACL entry.
aclcreateentry
This function creates a new ACL entry in the ACL indicated by acld.
If there is insufficient space in the ACL for creating a new entry,
then additional memory is allocated. The descriptor for this new ACL
entry is returned in entrydp. The components of the new ACL entry
are initialized so that the ACL tag type and qualifier are invalid,
and the set of permissions is empty. Use aclsettag() to set the
tag and qualifier and aclsetperm() to set the permissions on the
newly created entry.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
ENOMEM The ACL working storage requires more memory than the system
is able to provide.
acldeleteentry
This function removes the ACL entry entryd from the ACL that
contains it. entryd and any other ACL entry descriptors that refer
to the same ACL entry are undefined after this function.
Errors:
EINVAL entryd does not refer to a valid ACL entry.
acldeleteperm
This function deletes the set of permissions contained in perms from
the ACL entry entryd. Any permissions the ACL entry had prior to
the call to acldeleteperm() not specified in perms are left
unchanged. The acldeleteperm() function does not return an error
if the ACL entry does not have any of the specified permissions.
Errors:
EINVAL entryd does not refer to a valid ACL entry.
EINVAL perms contains values not defined in aclpermsett.
aclfree
This function releases the working storage associated with acld.
Any existing ACL entry descriptions that refer to entries in the ACL
become undefined.
Note that this function does not set the pointer acld to NULL.
Errors:
EINVAL acld does refer to an ACL allocated by aclalloc().
aclfromexport
This function translates the exportable text or data package referred
to by buf into the ACL working storage referred to by acld. Any ACL
in the working storage is overwritten. If there is insufficient
space in the acld working storage for translating the ACL, then
additional memory is allocated.
packtype may be one of the following values defined in <sys/acl.h>:
ACL_TEXT_PACKAGE The ACL format as output by the getacl(1) command.
Any ACL entry descriptors that previously referred to entries within
acld become undefined.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
EINVAL packtype is not a valid package type.
ENOMEM The ACL working storage requires more memory than the system
is able to provide.
aclgetentry
This function obtains a descriptor to the next ACL entry of acld.
entrydp is set to point to this ACL entry. acld must refer to an
ACL that was previously opened via a call to aclalloc().
The first call to aclgetentry() following a call to aclread(),
aclrewind() or aclfromexport() obtains the first ACL entry in the
ACL, as ordered by the system. Subsequent calls to aclgetentry()
obtain successive ACL entries, until the last entry is obtained.
After the last entry has been obtained, the value 0 is returned.
Calls to aclgetentry() do not modify any ACL entry or the ACL on
the object from which it may have been obtained in any way.
Subsequent operations using the returned ACL entry descriptor operate
on the ACL entry within the ACL in working storage (and do not modify
the ACL on the object from which it may have been obtained).
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
aclgetperm
This function retrieves the permissions from the ACL entry entryd
and returns them in perms. Any permissions the ACL entry has prior
to the call to aclgetperm() are left unchanged.
Errors:
EINVAL entryd does not refer to a valid ACL entry.
aclgettag
This function returns the tag type and qualifier of the tag for the
ACL entry entryd. Upon successful completion, the location referred
to by tagtype is set to the tag type of the ACL entry. The location
referred to by tagqualifier is set to the qualifier data contained
within the ACL entry. If the returned value of a tag type is
(acltagt) ACL_USER, ACL_USER_OBJ, or ACL_OTHER_OBJ, the type of
tagqualifier is uidt. If tagtype is (acltagt) ACL_GROUP,
ACL_GROUP_OBJ, or ACL_MASK_OBJ, the tag type of tagqualifier is
gidt.
Errors:
EINVAL entryd does not refer to valid ACL entry.
aclpackagesize
This function determines the number of bytes necessary to represent
the exportable data or text package as specified by packtype, for
the ACL in working storage specified by acld.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
EINVAL packtype is not a valid package type.
aclread
This function reads an object's access or default ACL into the
working storage referred to by acld. Any ACL already in the working
storage is overwritten. If there is insufficient space in acld to
perform the operation, then additional memory is allocated. path
points to a pathname naming the file object. type is used to
indicate the whether the access or default ACL is to be read. type
may be either ACL_TYPE_ACCESS or ACL_TYPE_DEFAULT.
The ACL in working storage is independent of the ACL on the file
object. The ACL in working storage does not participate in any
access control decision.
Errors:
EINVAL acld does not refer to an ACL allocated by
aclalloc().
EINVAL type is neither ACL_TYPE_ACCESS nor ACL_TYPE_DEFAULT.
ENOMEM The ACL working storage requires more memory than the
system is able to provide.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to the file object is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOTDIR type is ACL_TYPE_DEFAULT and path does not refer to a
directory.
ENOENT The named file object does not exist or path points to
an empty string.
aclrewind
This function sets the internal descriptor for acld such that a
subsequent call to aclgetentry() using the same acld will obtain
the first entry in the ACL.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
aclsetperm
This function sets the permissions of the ACL entry entryd to the
permissions contained in perms. The permissions of the ACL entry
prior to the call to aclsetperm() are replaced.
Errors:
EINVAL entryd does not refer to a valid ACL entry.
EINVAL perms contains values not defined in aclpermsett.
aclsettag
This function sets the tag type of an ACL entry to the tag type in
tagtype with a qualifier as specified by tagqualifier. If the tag
type is ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER_OBJ, or ACL_MASK_OBJ
the tagqualifier may be passed as a value of NULL.
Errors:
EINVAL entryd does not refer to a valid ACL entry.
EINVAL tagtype is not a valid tag type.
acltoexport
This function translates the ACL in working storage (acld) into the
memory referred to by buf in an exportable text package as specified
by packtype. The acltoexport() function will only package up to
buflen bytes.
packtype may be one of the following values defined in <sys/acl.h>:
ACL_TEXT_PACKAGE The ACL format as output by the getacl(1) command.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
EINVAL packtype is not a valid package type.
ENOMEM The space referred to by buf and buflen is not sufficient to
store the translated ACL.
aclvalid
This function checks the access ACL or the default ACL referred to by
acld for validity. The three required entries ACL_USER_OBJ,
ACL_GROUP_OBJ and ACL_OTHER_OBJ must exist exactly once in an access
ACL. If an access ACL contains four or more entries, then the
ACL_MASK_OBJ entry must exist exactly once. The qualifier field must
be unique among entries of the same tag type. A default ACL may have
zero entries, but if it does have entries they must follow the same
rules as entries in an access ACL.
Errors:
If any of the following conditions occur, the aclvalid() function
sets the location referred to by entrydp to the ACL entry in error.
EINVAL The ACL contains entries that are not unique.
If any of the following conditions occur, the aclvalid() function
sets the location referred to by entrydp to NULL.
EINVAL acld does not refer to an ACL allocated by aclalloc().
EINVAL One or more of the required entries is not present.
aclwrite
This function associates an ACL with a file object, or deletes a
default ACL from a directory. path points to the pathname of the
file object. type indicates whether an access or default ACL is
being written. type may be either ACL_TYPE_ACCESS or
ACL_TYPE_DEFAULT.
The entries in the ACL may have been obtained via a call to the
aclread() function, newly created via calls to the
aclcreateentry() function, or by translating text defining an ACL
with aclfromexport(). The argument path specified in the
aclwrite() call is not necessarily the same as the argument path
specified in the aclread() call. The ACL may be otherwise
manipulated by the various ACL functions.
A default ACL may be removed from a directory by writing an ACL
containing zero entries to that directory, i.e., an ACL created by
aclalloc().
The aclwrite() function will succeed only if the ACL is valid as
defined by the aclvalid() function.
Upon successful completion, aclwrite() sets the specified file
object's access ACL or default ACL (whichever is being written) to
that contained in acld. The file object's previous access or
default ACL is no longer in effect. No intermediate state will exist
where the previous ACL and the new ACL, or the previous default ACL
and the new default ACL, coexist in whole or in part. This call may
result in changes to the file's permission bits. If aclwrite() is
unsuccessful, neither the access ACL nor the default ACL of path will
be changed.
Errors:
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute write access to path is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOTDIR type is ACL_TYPE_DEFAULT and path does not refer to a
directory.
ENOENT The named file object does not exist or path points to
an empty string.
EINVAL acld does not refer to an ACL allocated by aclalloc()
or contains other errors. Use aclvalid() to determine
what errors are in the ACL.
EINVAL type is neither ACL_TYPE_ACCESS nor ACL_TYPE_DEFAULT.
EPERM The effective UID of the process does not match the
owner of the file object and the process does not have
appropriate privilege to write the ACL.
ENOSPC There was not enough space to store the entire ACL from
the working storage during the write of the ACL.
ENOSPC {_POSIX_ACL_PRESENT} is not in effect for path and the
ACL contains more than the three base entries
(ACL_USER_OBJ, ACL_GROUP_OBJ and ACL_OTHER_OBJ).
EROFS The named file object resides on a read-only file
system.
aclallocated
This function ensures that acld is a valid aclt structure as
returned by the aclalloc() function.
Errors:
EINVAL acld is not of a form as allocated by aclalloc().
aclclear
This function initializes the ACL working storage specified by acld
to the same state it would be set to if newly allocated by
aclalloc(), with the exception that any additional space that may
have been allocated for additional ACL entries is not returned to the
system.
Errors:
EINVAL acld does not refer to an ACL as allocated by aclalloc().
aclentryvalid
This function checks to ensure that entryd is a valid ACL entry.
This routine only ensures that entryd is a well formed ACL entry.
It does not ensure that this entry is not a duplicate.
Errors:
EINVAL entryd is not a valid ACL entry.
aclfprintf
This function prints the POSIX text description of the specified ACL
to the specified stream file. This function does not retrieve the
ACL from the object. Rather, the object information is only used to
properly construct the comments in the ACL text representation. This
ACL displayed is the ACL passed in acld.
The parameters are:
file is a stream file.
jecttype must be JECTOBJECT.
targtype can be TFILE, TFD, TPROC, TMSG, TSEM, or TSHM.
targ specifies a stream file.
acltype can be either ACLTYPEACCESS or ACLTYPEDEFAULT
(valid only when objtype is SecDirectoryFile).
objtype can be SecRegularFile or SecDirectoryFile.
acld is a correctly allocated ACL.
flags is one or more of the following options (separated by
the "OR" (|) operator):
ACLPRINTIDNAME
ACLPRINTEFFECTIVEPERM
ACLPRINTOBJECTNAME
ACLPRINTOWNINGUSER
ACLPRINTOWNINGGROUP
ACLPRINTSORTEDACL
maskptr is the address of a variable of type aclpermsett
which can be used to specify mask permissions when
printing an incomplete, invalid ACL.
Errors:
EINVAL acld is not an ACL allocated by aclalloc().
EINVAL One or more of the parameters is not as specified above.
ENOMEM There was insufficient space available from the system to
complete the operation.
aclgettext
This function allocates a character buffer and places the POSIX text
description of the specified ACL in that character buffer. Upon
successful completion, aclgettext returns the pointer to the
character buffer. If an error occurs, NULL is returned. This
function does not retrieve the ACL from the object. Rather, the
object information is only used to properly construct the comments in
the ACL text representation. This ACL displayed is the ACL passed in
acld.
The parameters are:
jecttype must be JECTOBJECT.
targtype can be TFILE, TFD, TPROC, TMSG, TSEM, or TSHM.
targ specifies the target object.
acltype can be either ACLTYPEACCESS or ACLTYPEDEFAULT
(valid only when objtype is SecDirectoryFile).
objtype can be SecRegularFile or SecDirectoryFile.
acld is a correctly allocated ACL.
flags is one or more of the following options (separated by
the "OR" (|) operator):
ACLPRINTIDNAME
ACLPRINTEFFECTIVEPERM
ACLPRINTOBJECTNAME
ACLPRINTOWNINGUSER
ACLPRINTOWNINGGROUP
ACLPRINTSORTEDACL
maskptr is the address of a variable of type aclpermsett
which can be used to specify mask permissions when
printing an incomplete, invalid ACL.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc() or
contains other errors. Use aclvalid() to determine what
errors are in the ACL.
EINVAL One or more of the parameters is not as specified above.
ENOMEM There was insufficient space available from the system to
complete the operation.
aclinternalclear
This function sets all storage specified by acld to zero. That is,
it removes the text and binary ACL if they exist. Note that if a
file has an extended ACL and it is removed, the file is left with a
minimum ACL.
aclinternalcopy
This function copies the ACL referenced by src into the ACL working
storage referenced by dest. If there is insufficient space in dest
to perform the operation, then additional memory is allocated. Any
ACL previously in dest is overwritten.
Errors:
EINVAL src or dest is not a valid acld as allocated by aclalloc().
EINVAL src and dest do not have the same structure revision number.
ENOMEM The ACL working storage requires more memory than the system
is able to provide.
aclinternalfree
This function frees all storage associated with acldp and sets the
pointer referred to by *acldp to NULL.
Errors:
EINVAL acldp is NULL.
aclnocalcmask
This function calculates a mask by taking the union of the
permissions of the entries in the File Group Class (ACL_GROUP_OBJ,
ACL_USER, and ACL_GROUP) and creates an ACL_MASK_OBJ entry in acld
if an ACL_MASK_OBJ entry does not currently exist. If one does
exist, then the function performs no action.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
ENOMEM The ACL working storage requires more memory than the system
is able to provide.
aclorder
This function reorders the entries of the specified ACL acld in the
following order:
ACL_USER_OBJ
ACL_GROUP_OBJ
ACL_OTHER_OBJ
ACL_MASK_OBJ
ACL_USER (ordered numerically by UID)
ACL_GROUP (ordered numerically by GID)
There is no check made for duplicate entries.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc().
aclprintf
This function prints the POSIX text description of the specified ACL
to standard output. This function does not retrieve the ACL from the
object. Rather, the object information is only used to properly
construct the comments in the ACL text representation. The ACL
displayed is the ACL passed in acld.
The parameters are:
jecttype must be JECTOBJECT.
targtype can be TFILE, TFD, TPROC, TMSG, TSEM, or TSHM.
targ specifies the target object.
acltype can be either ACLTYPEACCESS or ACLTYPEDEFAULT
(valid only when objtype is SecDirectoryFile).
objtype can be SecRegularFile or SecDirectoryFile.
acld is a correctly allocated ACL.
flags is one or more of the following options (separated by
the "OR" (|) operator):
ACLPRINTIDNAME
ACLPRINTEFFECTIVEPERM
ACLPRINTOBJECTNAME
ACLPRINTOWNINGUSER
ACLPRINTOWNINGGROUP
ACLPRINTSORTEDACL
maskptr is the address of a variable of type aclpermsett
which can be used to specify mask permissions when
printing an incomplete, invalid ACL.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc() or
contains other errors. Use aclvalid() to determine what
errors are in the ACL.
EINVAL One or more of the parameters is not as specified above.
ENOMEM There was insufficient space available from the system to
complete the operation.
aclreadject
This function reads the ACL of the specified object into the ACL
working storage specified by acld. If there is insufficient space
in the ACL for creating a new entry, then additional memory is
allocated. If the ACL_TYPE_DEFAULT option is specified, and if the
target object is a directory which does not have a default ACL, the
function will still return success, but acld will be empty on
return.
The parameters are:
jecttype must be JECTOBJECT.
targtype can be TFILE or TFD.
acltype can be either ACLTYPEACCESS or ACLTYPEDEFAULT
(valid only when objtype is SecDirectoryFile).
acld is a correctly allocated ACL.
flags is currently unused and must be set to 0.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc()
or contains other errors. Use aclvalid() to determine
what errors are in the ACL.
EINVAL One or more of the parameters is not as specified
above.
ENOMEM There was insufficient space available from the system
to complete the operation.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute read access to path is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOTDIR type is ACL_TYPE_DEFAULT and path does not refer to a
directory.
ENOENT The named file object does not exist or path points to
an empty string.
EINVAL type is neither ACL_TYPE_ACCESS nor ACL_TYPE_DEFAULT.
aclwriteject
This function writes the ACL specified by acld on the file object
specified. Any ACL previously associated with the file object is
overwritten.
The parameters are:
jecttype must be JECTOBJECT.
targtype can be TFILE or TFD.
acltype can be either ACLTYPEACCESS or ACLTYPEDEFAULT
(valid only when objtype is SecDirectoryFile).
acld is a correctly allocated ACL.
flags is currently unused and must be set to 0.
Errors:
EINVAL acld does not refer to an ACL allocated by aclalloc()
or contains other errors. Use aclvalid() to determine
what errors are in the ACL.
EINVAL One or more of the parameters is not as specified
above.
ENOMEM There was insufficient space available from the system
to complete the operation.
EACCES Search permission is denied on a component of the path
prefix.
EACCES Attribute write access to path is denied.
ENAMETOOLONG The length of path exceeds {PATH_MAX}, or a pathname
component is longer than {NAME_MAX} while
{POSIX_NO_TRUNC} is in effect.
ENOTDIR A component of the path prefix is not a directory.
ENOTDIR type is ACL_TYPE_DEFAULT and path does not refer to a
directory.
ENOENT The named file object does not exist or path points to
an empty string.
EINVAL type is neither ACL_TYPE_ACCESS nor ACL_TYPE_DEFAULT.
EPERM The effective UID of the process does not match the
owner of the file object and the process does not have
appropriate privilege to write the ACL.
ENOSPC There was not enough space to store the entire ACL from
the working storage during the write of the ACL.
ENOSPC {_POSIX_ACL_PRESENT} is not in effect for path and the
ACL contains more than the three base entries
(ACL_USER_OBJ, ACL_GROUP_OBJ and ACL_OTHER_OBJ).
EROFS The named file object resides on a read-only file
system.
SEE ALSO
getacl(1), setacl(1), dggetoacl(2), dgsetoacl(2), aalibrary(3),
auditlibrary(3), caplibrary(3), maclibrary(3).
Licensed material--property of copyright holder(s)