F$SETPRV()

From VSI OpenVMS Wiki
Jump to: navigation, search

F$SETPRV is a lexical function that enables or disables specified user privileges. The F$SETPRV function returns a list of keywords indicating user privileges; this list shows the status of the specified privileges before F$SETPRV was executed. Your process must be authorized to set the specified privilege.

Syntax

F$SETPRV(priv-states)

Return Value

A character string containing keywords for the current process privileges before they were changed by the F$SETPRV function. LEXICALS

Arguments

priv-states

Specifies a character string defining a privilege, or a list of privileges separated by commas (,).

Examples

$ OLDPRIV = F$SETPRV("OPER,NOTMPMBX") 
$ SHOW SYMBOL OLDPRIV OLDPRIV = "NOOPER,TMPMBX" 

In this example, the process is authorized to change the OPER (operator) and TMPMBX (temporary mailbox) privileges. The F$SETPRV function enables the OPER privilege and disables the TMPMBX privilege. In addition, the F$SETPRV function returns the keywords NOOPER and TMPMBX, showing the state of these privileges before they were changed. You must place quotation marks (" ") around the list of privilege keywords because it is a string literal.

 $ SHOW PROCESS/PRIVILEGE 
  05-JUN-2001 15:55:09.60   RTA1:              User: HELRIEGEL

           Process privileges:

           Process rights identifiers:
            INTERACTIVE
            LOCAL

 $ NEWPRIVS = F$SETPRV("ALL, NOOPER") 
 $ SHOW SYMBOL NEWPRIVS 
   NEWPRIVS = "NOCMKRNL,NOCMEXEC,NOSYSNAM,NOGRPNAM,NOALLSPOOL, 
   NOIMPERSONATE,NODIAGNOSE,NOLOG_IO,NOGROUP,NOACNT,NOPRMCEB, 
   NOPRMMBX,NOPSWAPM,NOALTPRI,NOSETPRV,NOTMPMBX,NOWORLD,NOMOUNT, 
   NOOPER,NOEXQUOTA,NONETMBX,NOVOLPRO,NOPHY_IO,NOBUGCHK,NOPRMGBL, 
   NOSYSGBL,NOPFNMAP,NOSHMEM,NOSYSPRV,NOBYPASS,NOSYSLCK,NOSHARE, 
   NOUPGRADE,NODOWNGRADE,NOGRPPRV,NOREADALL,NOSECURITY,OPER" 
 $ SHOW PROCESS/PRIVILEGE

           05-JUN-2001 10:21:18.32   User: INAZU      Process ID: 00000F24
                                     Node: TOKNOW     Process name: "_FTA23:"

           Authorized privileges:
            NETMBX    SETPRV    SYSPRV    TMPMBX

           Process privileges:
            ACNT                 may suppress accounting messages
            ALLSPOOL             may allocate spooled device
            ALTPRI               may set any priority value
            AUDIT                may direct audit to system security audit log
            BUGCHK               may make bug check log entries
            BYPASS               may bypass all object access controls
            CMEXEC               may change mode to exec
            CMKRNL               may change mode to kernel
            DIAGNOSE             may diagnose devices
            DOWNGRADE            may downgrade object secrecy
            EXQUOTA              may exceed disk quota
            GROUP                may affect other processes in same group
            GRPNAM               may insert in group logical name table
            GRPPRV               may access group objects via system protection
            IMPERSONATE          may impersonate another user
            IMPORT               may set classification for unlabeled object
            LOG_IO               may do logical i/o
            MOUNT                may execute mount acp function
            NETMBX               may create network device
            OPER                 may perform operator functions
            PFNMAP               may map to specific physical pages
            PHY_IO               may do physical i/o
            PRMCEB               may create permanent common event clusters
            PRMGBL               may create permanent global sections
            PRMMBX               may create permanent mailbox
            PSWAPM               may change process swap mode
            READALL              may read anything as the owner
            SECURITY             may perform security administration functions
            SETPRV               may set any privilege bit
            SHARE                may assign channels to non-shared devices
            SHMEM                may create/delete objects in shared memory
            SYSGBL               may create system wide global sections
            SYSLCK               may lock system wide resources
            SYSNAM               may insert in system logical name table
            SYSPRV               may access objects via system protection
            TMPMBX               may create temporary mailbox
            UPGRADE              may upgrade object integrity
            VOLPRO               may override volume protection
            WORLD                may affect other processes in the world

           Process rights:
            INTERACTIVE
            LOCAL

           System rights:
            SYS$NODE_TOKNOW

           $ NEWPRIVS = F$SETPRV(NEWPRIVS)
           $ SHOW PROCESS/PRIVILEGE

           05-JUN-2001 16:05:07.23   RTA1:              User: JERROM

           Process privileges:
            OPER                 operator privilege

           Process rights identifiers:
            INTERACTIVE
            LOCAL
 

In this example, the DCL command SHOW PROCESS/PRIVILEGE is used to determine the current process privileges. Note that the process has no privileges enabled. The F$SETPRV function is then used to process the ALL keyword and enable all privileges recording the previous state of each privilege in the symbol NEWPRIVS. Next, F$SETPRV processes the NOOPER keyword and disables the OPER (operator) privilege, recording the previous state of OPER in NEWPRIVS. Note that the OPER privilege appears in the returned string twice: first as NOOPER and then as OPER. Entering the command SHOW PROCESS/PRIVILEGE now shows that the current process has all privileges enabled except OPER. If the returned string is used as the parameter to F$SETPRV, the process has the OPER privilege enabled. This occurs because the OPER command was present twice in the symbol NEWPRIVS. As a result, F$SETPRV looked at the first keyword NOOPER and disabled the privilege. Finally, after processing several other keywords in the NEWPRIVS string, the OPER keyword is presented, allowing F$SETPRV to enable the OPER privilege.

If you are using the ALL or NOALL keywords to save your current privilege environment, VSI recommends that you perform the following procedure to modify the process for a command procedure:

$ CURRENT_PRIVS = F$SETPRV("ALL") 
$ TEMP = F$SETPRV("NOOPER") 

If you use this procedure, you can then specify the following command statement at the end of your command procedure so that the original privilege environment is restored: $ TEMP = F$SETPRV(CURRENT_PRIVS)

$ SAVPRIV = F$SETPRV("NOGROUP") 
$ SHOW SYMBOL SAVPRIV SAVPRIV = "GROUP" 
$ TEST = F$PRIVILEGE("GROUP") 
$ SHOW SYMBOL TEST 
  TEST = "TRUE" 

In this example, the process is not authorized to change the GROUP privilege; however, the F$SETPRV function still returns the current setting for the GROUP privilege. The F$PRIVILEGE function is used to see whether the process has GROUP privilege. The return string, TRUE, indicates that the process has GROUP privilege, even though the F$SETPRV function attempted to disable the privilege.