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


NAME
       dgsecstat - get file security attribute status information

SYNOPSIS
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <sys/dgtparms.h>

       int  dgsecstat(path, bufferptr, linkintent, version)
       char * path;
       struct dgsecstat * bufferptr;
       int    linkintent;
       unsigned short version;

   where:
       path         Address of a pathname
       bufferptr   Address of a dgsecstat buffer to fill
       linkintent  Instructions on what to do if the component of path is a
                    symbolic link: DGSTATEXAMINESYMLINK or
                    DGSTATFOLLOWSYMLINK
       version      Version of the struct dgsecstat packet to which
                    bufferptr refers; should be set to
                    DGSTATVERSIONNUMBER

DESCRIPTION
       Dgsecstat(2) returns the current security attributes status plus the
       current extended attributes (as would be returned by dgstat(2)) of
       the file named by path into the dgsecstat buffer at the location
       specified by bufferptr.  If path refers to a symbolic link and
       linkintent is DG_STAT_FOLLOW_SYMLINK, then file status for the
       target of the symbolic link is returned.  If path refers to a
       symbolic link and linkintent is DG_STAT_EXAMINE_SYMLINK, then file
       status for the symbolic link itself is returned.  If path does not
       refer to a symbolic link, then the value of linkintent is
       irrelevant, but it must be one of the aforementioned constants.  If
       dgsecstat fails, the contents of the buffer are undefined.

       The size and composition of the structure referred to by bufferptr
       is determined by the version parameter.  All calls to this function
       should use DG_STAT_VERSION_NUMBER for this parameter.  version allows
       for future revisions of struct dgsecstat to be handled in a
       compatible way.

       The interpretation of the file's attributes depends on the file's
       type [see dgsecstat(5), dgstat(5) and stat(5)].

ACCESS CONTROL
       If the file is governed by a MAC range, then the process's clearance
       must dominate the low end of the MAC range, or the file must have
       appropriate privilege.  Otherwise, MAC read permission to the named
       file is required.  The process must have permission to resolve path.

RETURN VALUE
       0      The dgsecstat operation was successful.

       -1     An error occurred.  errno is set to indicate the error.

DIAGNOSTICS
       Errno may be set to one of the following error codes:

       EINVAL         version is not a supported version of struct
                      dgsecstat.

       EINVAL         linkintent is not one of DG_STAT_EXAMINE_SYMLINK or
                      DG_STAT_FOLLOW_SYMLINK.

       EFAULT         bufferptr points to an invalid address.

       ENOENT         The file the pathname resolved to does not exist.

       ENOENT         A nonterminal component of the pathname does not
                      exist.

       ENOTDIR        A nonterminal component of the pathname was not a
                      directory or symbolic link.

       ENAMETOOLONG   The pathname exceeds the length limit for pathnames.

       ENAMETOOLONG   A component of the pathname exceeds the length limit
                      for filenames.

       ENOMEM         There are not enough system resources to resolve the
                      pathname or to expand a symbolic link.

       ELOOP          The number of symbolic links encountered during
                      pathname resolution exceeded MAXSYMLINKS.  A symbolic
                      link cycle is suspected.

       EPERM          The pathname contains a character not in the allowed
                      character set.

       EFAULT         The pathname does not completely reside in the
                      process's address space or the pathname does not
                      terminate in the process's address space.

       EACCES         The calling process does not have permission to
                      resolve the pathname.

SEE ALSO
       secstat(1), chmod(2), chown(2), creat(2), dgfstat(2), dgmstat(2),
       dgstat(2), fchmod(2), fchown(2), fstat(2), link(2), lstat(2),
       mknod(2), pipe(2), read(2), stat(2), time(2), unlink(2), utime(2),
       utimes(2), write(2), dgsecstat(5).

NOTES
       If the file is governed by a MAC range, then allowing the file's
       security attributes to be queried when the process does not have MAC
       read access to the file might be thought to be a covert channel.
       This is not the case, since only an element of the trusted computing
       base (TCB) can allow an object to be governed by a MAC range, and so
       by definition, this would not be a covert channel.

       However, there is the possibility of an administrator providing a
       path for a security breach if care is not taken.  If the owner of the
       object governed by a MAC range is set to a user who can create
       processes with MAC read access to the object, then that user can
       signal information to a process without MAC read access (i.e., at a
       lower process clearance), by converting an ACL between a minimum and
       an extended ACL.  The process at the lower clearance will be able to
       note this.  This risk can be minimized by careful assignment and
       monitoring of files governed by MAC labels, and by ensuring that the
       setting of ACLs is always audited.


Licensed material--property of copyright holder(s)