OpenVMS System Services Reference Manual

The valid priority intervals for specific scheduling policies might change in the future. Applications should, therefore, not use embedded numeric constants for scheduling priority, but should use the appropriate $GETSYI item codes to fetch the legal priority intervals. The application can then dynamically select a priority value that is within the interval. The $GETSYI item codes are:

SYI$_DEF_PRIO_MAX
SYI$_DEF_PRIO_MIN
SYI$_PSXFIFO_PRIO_MAX
SYI$_PSXFIFO_PRIO_MIN
SYI$_PSXRR_PRIO_MAX
SYI$_PSXRR_PRIO_MIN

See the Item Codes section of the $GETSYI service description for more information about these item codes.

nullarg

OpenVMS usage:	null_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Placeholding argument reserved to Digital.

DESCRIPTION

The Set Priority service changes the base priority of the process or, optionally, changes the scheduling policy of the process. The base priority is used to determine the order in which executable processes are to run.
The scheduling policy denotes the following:

The basic scheduling discipline (FIFO, round-robin, and so forth).
The preemption/compensation rules by which a running process is descheduled in favor of another process and, ultimately, rescheduled.

A source process can modify the priority or scheduling policy of a target process if any of the following are true:

The source and target processes are in the same job tree.
The source and target processes have the same UIC.
The source process has WORLD privilege enabled.
The source and target processes are in the same process group.

The value to which the priority of a process can be set can be subject to limitations. If the source has ALTPRI privilege enabled, the target can be set to any valid priority. Otherwise, the priority value specified by the source process is compared to the authorized priority of the target process and the smaller of the two values is used as the new base priority of the target process.
If you specify neither the pidadr nor the prcnam argument, $SETPRI sets the base priority of the calling process.
If the longword at address pidadr is the value 0, the PID of the target process is returned.
The base priority of a process remains in effect until specifically changed or until the process is deleted.
To determine the priority set by the $SETPRI service, use the Get Job/Process Information ($GETJPI) service.
Required Access or Privileges

Depending on the operation, the calling process might need one of the following privileges to use $SETPRI:

GROUP privilege to change the priority of a process in the same group, unless the target process has the same UIC as the calling process.
WORLD privilege to change the priority of any other process in the system.
ALTPRI privilege to set any process's priority to a value greater than the target process's initial base priority. If a process does not have ALTPRI privilege, the priority value specified by the source process is compared to the authorized priority of the target process and the smaller of the two values is used as the new base priority of the target process.

Required Quota

None
Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The process name string or string descriptor cannot be read by the caller, or the process identification or previous priority longword cannot be written by the caller.

SS$_ILLPOLICY An invalid scheduling policy was specified.

SS$_ILLPRIPOL Setting the process to the specified priority and/or policy would result in an illegal policy/priority combination. The illegal combination can occur between the SETPRI policy and priority parameters themselves, or it can occur between either of the parameters and the current policy and/or priority of the target process.

SS$_INCOMPAT The remote node is running an incompatible version of the operating system.

SS$_IVLOGNAM The process name string has a length of 0 or has more than 15 characters.

SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified.

SS$_NOPRIV The process does not have the privilege to affect other processes.

SS$_NOSUCHNODE The process name refers to a node that is not currently recognized as part of the cluster.

SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)

SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)

$SETPRN

Allows a process to establish or to change its own process name.

Format

SYS$SETPRN [prcnam]

C Prototype

int sys$setprn ( void *prcnam);

ARGUMENT

prcnam

OpenVMS usage: process_name

type: character-coded text string

access: read only

mechanism: by descriptor---fixed length string descriptor

Process name to be given to the calling process. The prcnam argument is the address of a character string descriptor pointing to a 1- to 15-character process name string. If you do not specify prcnam, the calling process is given no name.

DESCRIPTION

The Set Process Name service allows a process to establish or to change its own process name, which remains in effect until you change it (using $SETPRN) or until the process is deleted. Process names provide an identification mechanism for processes executing with the same group number. A process can also be identified by its process identification (PID).
Required Access or Privileges

None
Required Quota

None
Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The process name string or string descriptor cannot be read by the caller.

SS$_DUPLNAM The specified process name duplicates one already specified within that group.

SS$_IVLOGNAM The specified process name has a length of 0 or has more than 15 characters.

$SETPRT

Allows a process to change the protection on a page or range of pages.

Format

SYS$SETPRT inadr ,[retadr] ,[acmode] ,prot ,[prvprt]

C Prototype

int sys$setprt (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode, unsigned int prot, unsigned char *prvprt);

ARGUMENTS

inadr

OpenVMS usage: address_range

type: longword (unsigned)

access: read only

mechanism: by reference

Starting and ending virtual addresses of the range of pages whose protection is to be changed. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. Addresses are adjusted up or down to fall on CPU-specific page boundaries. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.
If the starting and ending virtual addresses are the same, the protection is changed for a single page.
retadr

OpenVMS usage: address_range

type: longword (unsigned)

access: write only

mechanism: by reference---array reference or descriptor

Starting and ending virtual addresses of the range of pages whose protection was actually changed by $SETPRT. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.
If an error occurs while the protection is being changed, $SETPRT writes into retadr the range of pages that were successfully changed before the error occurred. If no pages were affected before the error occurred, $SETPRT writes the value --1 into each longword of the 2-longword array.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode associated with the call to $SETPRT. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the access modes.
The $SETPRT service uses whichever of the following two access modes is least privileged: (1) the access mode specified by acmode or (2) the access mode of the caller. To change the protection of any page in the specified range, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.
prot

OpenVMS usage: page_protection

type: longword (unsigned)

access: read only

mechanism: by value

Page protection to be assigned to the specified pages. The prot argument is a longword value containing the protection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.
The $PRTDEF macro defines the following symbolic names for the protection codes.

Symbol Description

PRT$C_NA No access

PRT$C_KR Kernel read only

PRT$C_KW Kernel write

PRT$C_ER Executive read only

PRT$C_EW Executive write

PRT$C_SR Supervisor read only

PRT$C_SW Supervisor write

PRT$C_UR User read only

PRT$C_UW User write

PRT$C_ERKW Executive read; kernel write

PRT$C_SRKW Supervisor read; kernel write

PRT$C_SREW Supervisor read; executive write

PRT$C_URKW User read; kernel write

PRT$C_UREW User read; executive write

PRT$C_URSW User read; supervisor write

OpenVMS Alpha systems convert PRT$C_NA to the next highest protection, kernel-read.
If you specify the protection as the value 0, the protection defaults to kernel read only.
prvprt

OpenVMS usage: page_protection

type: byte (unsigned)

access: write only

mechanism: by reference

Protection previously assigned to the last page in the range. The prvprt argument is the address of a byte into which $SETPRT writes the protection of this page. The prvprt argument is useful only when protection for a single page is being changed.

Symbol	Description
PRT$C_NA	No access
PRT$C_KR	Kernel read only
PRT$C_KW	Kernel write
PRT$C_ER	Executive read only
PRT$C_EW	Executive write
PRT$C_SR	Supervisor read only
PRT$C_SW	Supervisor write
PRT$C_UR	User read only
PRT$C_UW	User write
PRT$C_ERKW	Executive read; kernel write
PRT$C_SRKW	Supervisor read; kernel write
PRT$C_SREW	Supervisor read; executive write
PRT$C_URKW	User read; kernel write
PRT$C_UREW	User read; executive write
PRT$C_URSW	User read; supervisor write

DESCRIPTION

The Set Protection on Pages service allows a process to change the protection on a page or range of pages.
Required Access or Privileges

None
Required Quota

If a process changes the protection for any pages in a private section from read only to read/write, $SETPRT uses the paging file (PGFLQUOTA) quota of the process.
For pages in global sections, the new protection can alter only copy-on-reference pages.
Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET, $MGBLSC, $PURGWS, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC, $UPDSECW

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The input address array cannot be read by the caller; the output address array or the byte to receive the previous protection cannot be written by the caller; or an attempt was made to change the protection of a nonexistent page.

SS$_EXQUOTA The process exceeded its paging file quota while changing a page in a read-only private section to a read/write page.

SS$_IVPROTECT The specified protection code has a numeric value of 1, less than 0, or greater than 15.

SS$_LENVIO A page in the specified range is beyond the end of the program or control region.

SS$_NOPRIV A page in the specified range is in the system address space; an attempt was made to change the protection of a valid global page, of an invalid global noncopy-on-reference page, or a PFN global or private page.

SS$_PAGOWNVIO The process attempted to change the protection on a page owned by a more privileged access mode.

$SETPRT_64 (Alpha Only)

On Alpha systems, allows a process to change the protection on a page or range of pages.
This service accepts 64-bit addresses.

Format

SYS$SETPRT_64 start_va_64 ,length_64 ,acmode ,prot ,return_va_64 ,return_length_64 ,return_prot_64

C Prototype

int sys$setprt_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, unsigned int prot, void *(*(return_va_64)), unsigned __int64 *return_length_64, unsigned int *return_prot_64);

ARGUMENTS

start_va_64

OpenVMS usage: address

type: quadword address

access: read only

mechanism: by value

The starting virtual address of the range of pages whose protection is to be changed. The specified virtual address will be rounded down to a CPU-specific boundary.
length_64

OpenVMS usage: byte count

type: quadword (unsigned)

access: read only

mechanism: by value

Length of the virtual address space whose protection is to be changed. The specified length will be rounded up to a CPU-specific page boundary so that it includes all CPU-specific pages in the requested range.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode associated with the call to $SETPRT_64. The acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in SYS$STARLET_C.TLB define the following symbols and their values for the four access modes:

Value Symbolic Name Access Mode

0 PSL$C_KERNEL Kernel

1 PSL$C_EXEC Executive

2 PSL$C_SUPER Supervisor

3 PSL$C_USER User

The most privileged access mode used is the access mode of the caller. To change the protection of any page in the specified range, the resultant access mode must be equal to or more privileged than the access mode of the owner of that page.
prot

OpenVMS usage: page_protection

type: longword (unsigned)

access: read only

mechanism: by value

Page protection to be assigned to the specified pages. The prot argument is a longword value containing the protection code. Only bits 0 to 3 are used; bits 4 to 31 are ignored.
The $PRTDEF macro for MACRO-32 and the include file PRTDEF.H for C define the symbolic names for the protection codes.
return_va_64

OpenVMS usage: address

type: quadword address

access: write only

mechanism: by 32- or 64-bit reference

The lowest process virtual address of the range of pages whose protection was actually changed. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the virtual address.
return_length_64

OpenVMS usage: byte count

type: quadword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

The length of the virtual address range whose protection was actually changed. The return_length_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length of the virtual address range in bytes.
return_prot_64

OpenVMS usage: page_protection

type: longword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

Protection previously assigned to the last page in the range. The return_prot_64 argument is the 32- or 64-bit virtual address of a naturally aligned longword into which $SETPRT_64 writes the protection of this page. The return_prot_64 argument is useful only when protection for a single page is being changed.

Value	Symbolic Name	Access Mode
0	PSL$C_KERNEL	Kernel
1	PSL$C_EXEC	Executive
2	PSL$C_SUPER	Supervisor
3	PSL$C_USER	User

DESCRIPTION

The Set Protection on Pages service allows a process to change the protection on a page or range of pages. For pages in a global section, the new protection can alter only copy-on-reference pages.
If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64, return_length_64, and return_prot arguments.
If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully changed before the error occurred. If no pages were changed, the return_va_64 argument will contain the value -1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.
Required Privileges

None
Required Quota

If a process changes the protection for any pages in a private section from read-only to read/write, $SETPRT_64 uses the paging file (PGFLQUOTA) quota of the process.
Related Services

$CRETVA_64, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64, $EXPREG_64, $MGBLSC_64

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The return_va_64 or the return_length_64 argument cannot be written by the caller.

SS$_EXPGFLQUOTA The process exceeded its paging file quota while changing a page in a read-only private section to a read/write page.

SS$_IVPROTECT The specified protection code has a numeric value of 1 or is greater than 15.

SS$_LENVIO A page in the specified range is not in process private address space.

SS$_NOSUCHPAG An attempt was made to change the protection on a nonexistent page.

SS$_PAGNOTINREG A page in the specified range is not within the specified region.

SS$_PAGTYPVIO A page in the specified range is not in process private address space.

SS$_PAGOWNVIO The process attempted to change the protection on a page owned by a more privileged access mode.

$SETPRV

Enables or disables specified privileges for the calling process.

Format

SYS$SETPRV [enbflg] ,[prvadr] ,[prmflg] ,[prvprv]

C Prototype

int sys$setprv (char enbflg, struct _generic_64 *prvadr, char prmflg, struct _generic_64 *prvprv);

ARGUMENTS

enbflg

OpenVMS usage: boolean

type: longword (unsigned)

access: read only

mechanism: by value

Indicator specifying whether the specified privileges are to be enabled or disabled. The enbflg argument is a longword value. The value 1 indicates that the privileges specified in the prvadr argument are to be enabled. The value 0 (the default) indicates that the privileges are to be disabled.
prvadr

OpenVMS usage: mask_privileges

type: quadword (unsigned)

access: read only

mechanism: by reference

Privileges to be enabled or disabled for the calling process. The prvadr argument is the address of a quadword bit vector wherein each bit corresponds to a privilege that is to be enabled or disabled.
Each bit has a symbolic name. The $PRVDEF macro defines these names. You form the bit vector by specifying the symbolic name of each desired privilege in a logical OR operation. Table SYS-15 provides the symbolic name and description of each privilege.

Table SYS-15 User Privileges
Privilege Symbolic Name Description

ACNT PRV$M_ACNT Create processes for which no accounting is done

ALLSPOOL PRV$M_ALLSPOOL Allocate a spooled device

ALTPRI PRV$M_ALTPRI Set (alter) any process priority

AUDIT PRV$V_AUDIT Generate audit records

BUGCHK PRV$M_BUGCHK Make bugcheck error log entries

BYPASS PRV$M_BYPASS Bypass all protection

CMEXEC PRV$M_CMEXEC Change mode to executive

CMKRNL PRV$M_CMKRNL Change mode to kernel

DETACH PRV$M_DETACH Create detached processes

DIAGNOSE PRV$M_DIAGNOSE Can diagnose devices

DOWNGRADE PRV$V_DOWNGRADE Can downgrade classification

EXQUOTA PRV$M_EXQUOTA Can exceed quotas

GROUP PRV$M_GROUP Group process control

GRPNAM PRV$M_GRPNAM Place name in group logical name table

GRPPRV PRV$V_GRPPRV Group access by means of system protection field

IMPORT PRV$V_IMPORT Mount a nonlabeled tape volume

LOG_IO PRV$M_LOG_IO Perform logical I/O operations

MOUNT PRV$M_MOUNT Issue mount volume QIO

NETMBX PRV$M_NETMBX Create a network device

OPER PRV$M_OPER All operator privileges

PFNMAP PRV$M_PFNMAP Map to section by physical page frame number

PHY_IO PRV$M_PHY_IO Perform physical I/O operations

PRMCEB PRV$M_PRMCEB Create permanent common event flag clusters

PRMGBL PRV$M_PRMGBL Create permanent global sections

PRMMBX PRV$M_PRMMBX Create permanent mailboxes

PSWAPM PRV$M_PSWAPM Change process swap mode

READALL PRV$V_READALL Possess read access to everything

SECURITY PRV$V_SECURITY Can perform security functions

SETPRV PRV$M_SETPRV Set any process privileges

SHARE PRV$M_SHARE Can assign a channel to a nonshared device

SHMEM PRV$M_SHMEM Allocate structures in memory shared by multiple processors

SYSGBL PRV$M_SYSGBL Create system global sections

SYSLCK PRV$M_SYSLCK Queue systemwide locks

SYSNAM PRV$M_SYSNAM Place name in system logical name table

SYSPRV PRV$M_SYSPRV Access files and other resources as if you have a system UIC

TMPMBX PRV$M_TMPMBX Create temporary mailboxes

UPGRADE PRV$V_UPGRADE Can upgrade classification

VOLPRO PRV$M_VOLPRO Override volume protection

WORLD PRV$M_WORLD World process control

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P066.HTM
  OSSG Documentation
  22-NOV-1996 13:00:30.49
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The process name string or string descriptor cannot be read by the caller, or the process identification or previous priority longword cannot be written by the caller.
SS$_ILLPOLICY	An invalid scheduling policy was specified.
SS$_ILLPRIPOL	Setting the process to the specified priority and/or policy would result in an illegal policy/priority combination. The illegal combination can occur between the SETPRI policy and priority parameters themselves, or it can occur between either of the parameters and the current policy and/or priority of the target process.
SS$_INCOMPAT	The remote node is running an incompatible version of the operating system.
SS$_IVLOGNAM	The process name string has a length of 0 or has more than 15 characters.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.
SS$_NOPRIV	The process does not have the privilege to affect other processes.
SS$_NOSUCHNODE	The process name refers to a node that is not currently recognized as part of the cluster.
SS$_REMRSRC	The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)
SS$_UNREACHABLE	The remote node is a member of the cluster but is not accepting requests. (This is normal for a brief period early in the system boot process.)

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed length string descriptor

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	page_protection
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by value

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	boolean
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	mask_privileges
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Privilege	Symbolic Name	Description
ACNT	PRV$M_ACNT	Create processes for which no accounting is done
ALLSPOOL	PRV$M_ALLSPOOL	Allocate a spooled device
ALTPRI	PRV$M_ALTPRI	Set (alter) any process priority
AUDIT	PRV$V_AUDIT	Generate audit records
BUGCHK	PRV$M_BUGCHK	Make bugcheck error log entries
BYPASS	PRV$M_BYPASS	Bypass all protection
CMEXEC	PRV$M_CMEXEC	Change mode to executive
CMKRNL	PRV$M_CMKRNL	Change mode to kernel
DETACH	PRV$M_DETACH	Create detached processes
DIAGNOSE	PRV$M_DIAGNOSE	Can diagnose devices
DOWNGRADE	PRV$V_DOWNGRADE	Can downgrade classification
EXQUOTA	PRV$M_EXQUOTA	Can exceed quotas
GROUP	PRV$M_GROUP	Group process control
GRPNAM	PRV$M_GRPNAM	Place name in group logical name table
GRPPRV	PRV$V_GRPPRV	Group access by means of system protection field
IMPORT	PRV$V_IMPORT	Mount a nonlabeled tape volume
LOG_IO	PRV$M_LOG_IO	Perform logical I/O operations
MOUNT	PRV$M_MOUNT	Issue mount volume QIO
NETMBX	PRV$M_NETMBX	Create a network device
OPER	PRV$M_OPER	All operator privileges
PFNMAP	PRV$M_PFNMAP	Map to section by physical page frame number
PHY_IO	PRV$M_PHY_IO	Perform physical I/O operations
PRMCEB	PRV$M_PRMCEB	Create permanent common event flag clusters
PRMGBL	PRV$M_PRMGBL	Create permanent global sections
PRMMBX	PRV$M_PRMMBX	Create permanent mailboxes
PSWAPM	PRV$M_PSWAPM	Change process swap mode
READALL	PRV$V_READALL	Possess read access to everything
SECURITY	PRV$V_SECURITY	Can perform security functions
SETPRV	PRV$M_SETPRV	Set any process privileges
SHARE	PRV$M_SHARE	Can assign a channel to a nonshared device
SHMEM	PRV$M_SHMEM	Allocate structures in memory shared by multiple processors
SYSGBL	PRV$M_SYSGBL	Create system global sections
SYSLCK	PRV$M_SYSLCK	Queue systemwide locks
SYSNAM	PRV$M_SYSNAM	Place name in system logical name table
SYSPRV	PRV$M_SYSPRV	Access files and other resources as if you have a system UIC
TMPMBX	PRV$M_TMPMBX	Create temporary mailboxes
UPGRADE	PRV$V_UPGRADE	Can upgrade classification
VOLPRO	PRV$M_VOLPRO	Override volume protection
WORLD	PRV$M_WORLD	World process control