dg_get_required_cap(2)   DG/UX B2 Security R4.12MU02  dg_get_required_cap(2)


NAME
       dg_get_required_cap - read an object's required capability set.

SYNOPSIS
       #include <sys/capability.h>
       #include <sys/dg_tparms.h>

       int     dg_get_required_cap(targ_type, targ, rcap_p)
       const int     targ_type;
       const void      *targ;
       cap_required_t     *rcap_p;

   where:
       targ_type  A token that identifies the type of object whose required
                  capability set is to be read.  The available tokens are
                  defined in sys/dg_tparms.h as follows:
                    T_FILE  The object is a file identified by a pathname.
                    T_FD    The object is a file, socket or pipe identified
                            by a descriptor.
                    T_MSG   The object is a message queue identified by a
                            message queue identifier.
                    T_SHM   The object is a shared memory segment identified
                            by a shared memory segment identifier.
                    T_SEM   The object is a semaphore identified by a
                            semaphore set identifier.

       targ       The address of the identifier of the object whose required
                  capability set is to be read.  The value of targ_type
                  determines the type of entity that targ points to as
                  follows:
                    T_FILE  targ points to a pathname string.
                    T_FD    targ points to a file, socket or pipe
                            descriptor.
                    T_MSG   targ points to a message queue identifier.
                    T_SHM   targ points to a shared memory segment
                            identifier.
                    T_SEM   targ points to a semaphore set identifier.

       rcap_p     Points to the structure into which the target's
                  cap_required_t is read.

DESCRIPTION
       This system call copies the required capability set structure
       (cap_required_t) from targ to the structure pointed to by rcap_p.
       When the object has no required set the call fails and rcap_p is not
       modified.

ACCESS CONTROL
       The required set 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:

       ENOSYS       This system call was made on a system that does not have
                    the _POSIX_CAP configuration option enabled.

       EACCES       Search permission is denied for a non-terminal component
                    of targ.

       EACCES       On a system with DG/UX information security, MAC read
                    access is denied.

       EFAULT       The parameter rcap_p 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.

       EDGNOATTR    The object given by targ does not have a required
                    capability set.

       ENAMETOOLONG The value of targ_type is T_FILE and 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.

SEE ALSO
       dg_set_required_cap(2), cap_defaults(5)


Licensed material--property of copyright holder(s)