dg_getoacl(2) DG/UX B2 Security R4.12MU02 dg_getoacl(2)
NAME
dggetoacl - get the access control list (ACL) for an object
SYNOPSIS
#include <sys/types.h>
#include <sys/dgtparms.h>
#include <sys/acl.h>
int dggetoacl(targtype, targ, type, acl, aclsize, textacl,
textaclsize)
int targtype;
const void *targ;
int type;
aclstructt *acl;
int *aclsize;
char *textacl;
int *textaclsize;
where:
targtype A token that identifies the type of object whose ACL is
fetched. The available tokens are defined in
sys/dgtparms.h as follows:
TFILE The object is a file identified by a
pathname.
TSYMLINK The object is a file identified by a
pathname. If the terminal component of the
pathname is a symbolic link, the link is
not followed.
TFD The object is a file, socket or pipe
identified by a descriptor.
TMSG The object is a message queue identified by
a message queue identifier.
TSHM The object is a shared memory segment
identified by a shared memory segment
identifier.
TSEM The object is a semaphore identified by a
semaphore set identifier.
targ The address of the identifier of the object whose ACL is
fetched. The value of targtype determines the type of
entity that targ points to as follows:
TFILE targ points to a pathname string.
TSYMLINK The object is a file identified by a
pathname. If the terminal component of the
pathname is a symbolic link, the link is
not followed.
TFD targ points to a file, socket or pipe
descriptor.
TMSG targ points to a message queue identifier.
TSHM targ points to shared memory segment
identifier.
TSEM targ points to a semaphore set identifier.
type type indicates whether the call fetches an access ACL or
a default ACL. type must be set to either
ACLTYPEDEFAULT or ACLTYPEACCESS. Note that default
ACLs may only exist on directories.
acl The address of an aclstructt buffer to receive the
binary ACL.
aclsize A pointer to the size, in bytes, of the aclstructt
structure pointed to by acl; when zero, the binary ACL
is not fetched. If a default ACL is requested but does
not exist on the target directory the size pointed to by
aclsize is set to zero. An aclstructt is actually a
variable size structure with a fixed "header" (see
sys/acl.h). If the buffer supplied to dggetoacl is too
small, the call returns -1, sets errno to E2BIG, and
stores the correct size at aclsize.
textacl A pointer to a buffer to receive the ASCII text ACL
stored with this object. If no text ACL exists, the
size pointed to by textaclsize is set to zero.
Note that there is no assurance that the binary ACL
stored with the object will match the binary ACL that is
generated by converting the ASCII text ACL to binary.
Only the binary ACL is used by the reference monitor for
access control decisions.
textaclsize A pointer to the size in bytes of the text ACL. If this
parameter points to zero, dggetoacl assumes that it is
not to fetch the text ACL. If the buffer passed is too
small, dggetoacl stores the required size in
textaclsize, returns -1, and sets errno to E2BIG.
DESCRIPTION
The dggetoacl system call gets the ACL for the object identified by
targtype and targ and stores it in the buffer pointed to by acl.
Systems that support DG/UX Information Security at the B2 or C2 level
of security ignore the textacl and textaclsize parameters.
If the size given for the binary or text ACL is non-zero but not big
enough to hold the requested ACL, the correct size is returned in
aclsize and/or textaclsize, and neither ACL is fetched. When either
buffer is bigger than necessary the ACL is fetched and the actual
size(s) returned. Therefore, the caller must not only check for an
errno of E2BIG, but must also determine whether the value stored in
aclsize or textaclsize has changed.
ACCESS CONTROL
To get the ACL of an object, a process must have MAC read access to
the object or have appropriate privilege.
For systems supporting the DG/UX Capability Option, appropriate
privilege is defined as having one or more specific capabilities
enabled in the effective capability set of the calling process. See
capdefaults(5) for the default capability for this system call. On
systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
When the object is a file identified by a pathname the process must
also have sufficient access to resolve the pathname.
RETURN VALUE
0 Successful completion.
-1 An error occurred. errno is set to indicate the error.
EXCEPTIONS
Errno may be set to one of the following error codes:
EINVAL The ACL type indicated in the type parameter is not
ACLTYPEDEFAULT or ACLTYPEACCESS.
EINVAL The object type indicated in the targtype parameter is
not valid.
EINVAL The pointer for aclsize was NULL.
EOPNOTSUPP The object type indicated in the targtype parameter does
not support ACLs or the type parameter is ACL_TYPE_DEFAULT
and the object type indicated in the targ_type parameter
does not support default ACLs.
ENOTDIR The process attempted to get a default ACL for some object
other than a directory. This code is returned where
targ_type represents a valid object type, but the
particular object is not a directory.
EDGNOATTR The target object does not have any of the requested ACL
attributes. For example, both a text and default ACLs
were requested but the directory had neither. Note that
in this example if any one of the requested types was
found it would be returned, the size of the missing type
would be set to zero and no error would be returned.
ENOENT The object does not exist.
E2BIG One or both of the supplied buffers was too small. Note,
the size parameter(s) are set to the correct size(s) at
the time of the call.
EFAULT One of the parameters specified an area of memory not
accessible to the calling process.
ENOMEM The operating system was unable to allocate internal
memory to process the system call.
SEE ALSO
dgsetoacl(2), capdefaults(5).
Licensed material--property of copyright holder(s)