dg_getcap(2) DG/UX B2 Security R4.12MU02 dg_getcap(2)
NAME
dggetcap - read a target's capability state.
SYNOPSIS
#include <sys/capability.h>
#include <sys/dgtparms.h>
int dggetcap(targtype, targ, select, capp)
const int targtype;
const void *targ;
const capflagt select;
capt capp;
where:
targtype A token that identifies the type of object whose
capability state is to be read. The available tokens are
defined in sys/dgtparms.h as follows:
TPROC The object is an existing process on the system.
TFILE The object is a file identified by a pathname.
TFD The object is a file, socket or pipe identified
by a descriptor.
targ The address of the identifier of the object whose
capability state is to be read. The value of targtype
determines the type of entity that targ points to as
follows:
TPROC targ points to a process id (type pidt).
TFILE targ points to a pathname string.
TFD targ points to a file, socket or pipe
descriptor.
select A flag, set to select the sets of the target's capability
structure to be read. The available tokens are defined in
sys/capability.h as follows:
CAPEFFECTIVE This flag selects the effective
capability set.
CAPPERMITTED This flag selects the permitted
capability set.
CAPINHERITABLE
This flag selects the inheritable
capability set.
CAPBOUNDING This flag selects the bounding capability
set.
DGCAPSELECTNONE
This value selects no capability set, in
which case all sets in capp are set to
zero. In this case, only the type,
version, size and attrs fields are copied
to capp.
capp Points to the structure into which the requested
information from the target's capability structure is
copied.
DESCRIPTION
This system call copies selected capability sets, and all other
fields, from the capability structure of targ to the capability
structure pointed to by capp. Sets that are not selected are set to
zero in capp.
The sets to be read from the target are selected by enabling the
appropriate flags in select.
For all values of select, all fields of the target's capability
structure that are not capability sets are copied to capp.
When this call succeeds capp->attrs is set as follows:
DGCAPOBJHASEFFECTIVE When this flag is enabled the object
has an effective capability set.
DGCAPOBJHASPERMITTED When this flag is enabled the object
has a permitted capability set.
DGCAPOBJHASINHERITABLE When this flag is enabled the object
has an inheritable capability set.
DGCAPOBJHASBOUNDING. When this flag is enabled the object
has a bounding capability set.
DGCAPSUBJSETEFFECTIVE When this flag is enabled the process
has the SET-EFFECTIVE attribute
enabled. This attrs flag is only valid
for processes.
ACCESS CONTROL
The capability state is read if the caller has search access to the
pathname given by targ, or when targ is not a pathname but is a valid
identifier of an object. On a system with DG/UX information
security, when MAC is configured the caller must also have MAC read
access to the target.
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 One or more bits enabled in select are not defined for
type capability capflagt.
ENOSYS This system call was made on a system that does not have
the POSIXCAP configuration option enabled.
EACCES Search permission is denied for a non-terminal component
of targ.
EACCES MAC read access to the target is denied.
EFAULT The parameter capp points to a memory area not
accessible to the calling process.
ENOENT The object that targ resolved to does not exist or a
non-terminal component of the pathname does not exist.
ESRCH The process pid does not exist.
EDGNOATTR The object given by targ does not have a capability
state.
ENAMETOOLONG The pathname exceeds the length limit for pathnames.
ELOOP The number of symbolic links encountered during pathname
resolution exceeded MAXSYMLINKS. A symbolic link cycle
is suspected.
ENOTDIR A non-terminal component of a given path name is not a
directory.
EOPNOTSUPP This operation is not supported for the specified
object.
ENOMEM The operating system was unable to allocate internal
memory to process the system call.
EINVAL The object type indicated in the targtype parameter is
not valid.
SEE ALSO
dgsetcap(2), dggetrequiredcap(2), dgsetrequiredcap(2),
capdefaults(5).
Licensed material--property of copyright holder(s)