VMS Help System Services, $GET SECURITY  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Retrieves the security characteristics of an object.

    Format

      SYS$GET_SECURITY  [clsnam] ,[objnam] ,[objhan] ,[flags]

                        ,[itmlst] ,[contxt] ,[acmode]

    C Prototype

      int sys$get_security  ( void *clsnam, void *objnam, unsigned

                            int *objhan, unsigned int flags, void

                            *itmlst, unsigned int *contxt, unsigned

                            int *acmode);

1 - Arguments

 clsnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the object class. The clsnam argument is the address of a
    descriptor pointing to a string containing the name of the object
    class.

    The following is a list of protected object class names:

       CAPABILITY
       COMMON_EVENT_CLUSTER
       DEVICE
       FILE
       GLXSYS_GLOBAL_SECTION
       GLXGRP_GLOBAL_SECTION
       GROUP_GLOBAL_SECTION
       ICC_ASSOCIATION
       LOGICAL_NAME_TABLE
       QUEUE
       RESOURCE_DOMAIN
       SECURITY_CLASS
       SYSTEM_GLOBAL_SECTION
       VOLUME

 objnam

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor
    Name of the protected object whose associated security profile
    is going to be retrieved. The objnam argument is the address
    of a descriptor pointing to a string containing the name of the
    protected object.

    The format of an object name is class specific. The following
    table lists object names and describes their formats:

    Object Class        Object Name Format

    CAPABILITY          A character string. Currently, the only
                        capability object is VECTOR.
    COMMON_EVENT_       Name of the event flag cluster, as defined
    CLUSTER             in the Associate Common Event Flag Cluster
                        ($ASCEFC) system service.
    DEVICE              Standard device specification, described in
                        the OpenVMS User's Manual.
    FILE                Standard file specification, described in the
                        OpenVMS User's Manual.
    GROUP_GLOBAL_       Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.
    ICC_ASSOCIATION     ICC security object name node::association_
                        name. The special node name, ICC$::, refers
                        to entries in the clusterwide registry. For
                        registry entries, the Access Access Type does
                        not apply.
    LOGICAL_NAME_TABLE  Table name, as defined in the Create Logical
                        Name Table ($CRELNT) system service.
    QUEUE               Standard queue name, as described in the Send
                        to Job Controller ($SNDJBC) system service.
    RESOURCE_DOMAIN     An identifier or octal string enclosed in
                        brackets.
    SECURITY_CLASS      Any class name shown in column 1, or a
                        class name followed by a period (.) and
                        the template name. Use the DCL command SHOW
                        SECURITY to display possible template names.
    SYSTEM_GLOBAL_      Section name, as defined in the Create and
    SECTION             Map Section ($CRMPSC) system service.
    VOLUME              Volume name or name of the device on which
                        the volume is mounted.

 objhan

    OpenVMS usage:object_handle
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Data structure identifying the object whose associated
    characteristics are going to be retrieved. The objhan argument
    is an address of a longword containing the object handle. You can
    use the objhan argument as an alternative to the objnam argument;
    for example, channel number clearly specifies the file open on
    the channel and can serve as an object handle.

    The following table shows the format of the object classes:

    Object Class           Object Handle Format

    COMMON_EVENT_CLUSTER   Event flag number
    DEVICE                 Channel number
    FILE                   Channel number
    RESOURCE_DOMAIN        Resource domain identifier
    VOLUME                 Channel number

 flags

    OpenVMS usage:flags
    type:         mask_longword
    access:       read only
    mechanism:    by value
    Mask specifying processing options. The flags argument is a
    longword bit vector wherein a bit, when set, specifies the
    processing option. The flags argument requires the contxt
    argument.

    The following table describes each flag:

    Symbolic Name   Description

    OSS$M_RELCTX    Release the context structure at the completion
                    of this request.

    OSS$M_WLOCK     Maintain a write lock on the security profile
                    at the completion of this request. $GET_SECURITY
                    ignores the flag if the context has already been
                    established.

    These symbolic names are defined in the $OSSDEF macro. You
    construct the flags argument by specifying the symbolic names
    of each flag.

 itmlst

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item list specifying which information about the process or
    processes is to be returned. The itmlst argument is the address
    of a list of item descriptors, each of which describes an item
    of information. The list of item descriptors is terminated by a
    longword of 0.

    With the item list, the user retrieves the protected object's
    characteristics. The user defines which security characteristics
    to retrieve. If this argument is not present, only the flags
    argument is processed. Without the itmlst argument, you can only
    manipulate the security profile lock or release contxt resources.

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagram and descriptor fields table.

 contxt

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value used to maintain the processing context when dealing with
    a single protected object across multiple $GET_SECURITY/$SET_
    SECURITY calls. Whenever the context value is nonzero, the class
    name, object name, or object handle arguments are disregarded.
    An input value of 0 indicates that a new context should be
    established.

    Because an active context block consumes process memory, be sure
    to release the context block by setting the RELCTX flag when the
    profile processing is complete. $GET_SECURITY sets the context
    argument to 0 once the context is released.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Access mode to be used in the object protection check. The acmode
    argument is the address of a longword containing the access mode.
    The acmode argument defaults to kernel mode; however, the system
    compares acmode with the caller's access mode and uses the least
    privileged mode. The access modes are defined in the system macro
    $PSLDEF library. Compaq recommends that this argument be omitted
    (passed as zero).