HP OpenVMS System Services Reference Manual


Previous Contents Index


$SETFLT

On Alpha and Integrity server systems, allows a process to change the fault characteristic on a page or range of pages.

Format

SYS$SETFLT inadr ,[retadr] ,[acmode] ,fault_flag


C Prototype

int sys$setflt (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode, unsigned int fault_flag);


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 fault characteristic 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 fault characteristic 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 fault characteristic was actually changed by $SETFLT. 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 fault characteristic is being changed, $SETFLT writes into retadr the range of pages that were successfully changed before the error occurred. If no pages were affected before the error occurred, $SETFLT 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 $SETFLT. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the access modes.

The $SETFLT service uses whichever of the following two access modes is less privileged: (1) the access mode specified by acmode or (2) the access mode of the caller. To change the fault characteristic 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.

fault_flag


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

Flag mask specifying the request options. The fault_flag argument is a longword bit vector in which each bit corresponds to a flag. The $FLTDEF macro and the FLTDEF.H file define a symbolic name for each flag.

The $FLTDEF macro defines the following symbolic names for the fault characteristic codes:
Symbol Description
FLT$M_NO_EXECUTE Fault on execute access attempt
FLT$M_EXECUTABLE Allow execute access

If you specify the fault characteristic as the value 0, the characteristic defaults to no execute access.


Description

The Set Fault Characteristic on Pages service allows a process to change the fault characteristic on a page or range of pages.

Required Access or Privileges

None

Required Quota

None

Related Services

$CRETVA, $EXPREG, $SETPRT


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 fault characteristic of a nonexistent page.
SS$_BADPARAM A bad fault_flag argument was specified.
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.
SS$_PAGOWNVIO The process attempted to change the fault characteristic on a page owned by a more privileged access mode.

$SETFLT_64

On Alpha and Integrity server systems, allows a process to change the fault characteristic (for example, no execute) on a page or range of pages.

Format

$SETFLT_64 start_va_64 ,length_64 ,acmode ,fault_flag ,return_va_64 ,return_length_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 fault characteristic is to be changed. The specified virtual address will be rounded down to a CPU-specifie page boundary.

length_64


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

Length of the virtual address space whose fault characteristic 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 $SETFLT_64. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the four access modes.

The most privileged access mode used is the access mode of the caller. The calling process can modify pages only if those pages are owned by an access mode equal to or less privileged than the access mode of the calling process.

fault_flag


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

Flag mask specifying the request options. The fault_flag argument is a longword bit vector in which each bit corresponds to a flag. The $FLTDEF macro and the FLTDEF.H file define a symbolic name for each flag.

The $FLTDEF macro defines the following symbolic names for the fault characteristic codes:
Symbol Description
FLT$M_NO_EXECUTE Fault on execute access attempt
FLT$M_EXECUTABLE Allow execute access

If you specify the fault characteristic as the value 0, the characteristic defaults to no execute access.

return_va_64


OpenVMS usage: address
type: quadword address
access: write only
mechanism: by 32-bit or 64-bit reference

The lowest process virtual address of the range of pages whose fault characteristics were actually changed.

return_length_64


OpenVMS usage: byte count
type: quadword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference

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

Description

The Set Fault Characteristic service sets the fault characteristics (for example, no execute) for the specified range of pages, checking that the specified mode is at least as privileged as the owner of the page.

If the condition value SS$_ACCVIO is returned by this service, a value might not be returned in the memory locations pointed to by the return_va_64 and return_length_64 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 might not be returned in the memory location pointed to by the return_length_64 argument.

Required Privileges

None

Required Quota

None

Related Services

$CRETVA_64, $EXPREG_64, $SETPRT_64


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The return_va_64 or return_length_64 argument cannot be written by the caller.
SS$_BADPARAM A bad fault_flag argument was specified.
SS$_LENVIO A page in the specified range is beyond the length of virtual addresses within that region.
SS$_NOSUCHPAG An attempt was made to change the fault characteristic on a nonexistent page.
SS$_PAGNOTINREG A page in the specified range is not in process private adress space.
SS$_PAGOWNVIO The process attempted to change the protection on a page owned by a more privileged access mode.

$SETIME

Changes the value of, or recalibrates, the system time.

On Alpha and Integrity server systems, this service accepts 64-bit addresses.


Format

SYS$SETIME [timadr]


C Prototype

int sys$setime (struct _generic_64 *timadr);


Argument

timadr


OpenVMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha and Integrity servers)

New absolute time value for the system time, specifying the number of 100-nanosecond intervals since 00:00 o'clock, November 17, 1858. The timadr argument is the 32- or 64-bit address (on Alpha and Integrity server systems) of a quadword containing the new system time value. A negative (delta) time value is invalid.

If you do not specify the value of timadr or specify it as 0, $SETIME recalibrates the system time using the time-of-year clock.


Description

The Set System Time service (1) changes the value of or (2) recalibrates the system time, which is defined by a quadword value that specifies the number of 100-nanosecond intervals since 00:00 o'clock, November 17, 1858.

System time is the reference used for nearly all timer-related software activities in the operating system. After changing or recalibrating the system clock, $SETIME updates the timer queue by adjusting each element in the timer queue by the difference between the previous system time and the new system time.

The $SETIME service saves the new time (for future bootstrap operations) in the system image SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE on Alpha and Integrity server systems. To save the time, the service assigns a channel to the system boot device and calls $QIOW. You need the LOG_IO user privilege to perform this operation.

Required Access or Privileges

To set system time, the calling process must have OPER, LOG_IO, and SYSPRV privileges.

Required Quota

None

Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIMR


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The quadword that contains the new system time value cannot be read by the caller.
SS$_IVTIME The caller specified no time value or a negative time value and an invalid processor clock was found.
SS$_NOIOCHAN No I/O channel is available for assignment.
SS$_NOPRIV The process does not have the privileges to set the system time.

$SETIMR

Sets the timer to expire at a specified time.

On Alpha and Integrity server systems, this service accepts 64-bit addresses.


Format

SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]


C Prototype

int sys$setimr (unsigned int efn, struct _generic_64 *daytim, void (*astadr)(__unknown_params), unsigned __int64 reqidt, unsigned int flags);


Arguments

efn


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

Event flag to be set when the timer expires. The efn argument is a longword value containing the number of the event flag; however, $SETIMR uses only the low-order byte.

If you do not specify efn, event flag 0 is used.

When $SETIMR first executes, it clears the specified event flag or event flag 0.

daytim


OpenVMS usage: date_time
type: quadword
access: read only
mechanism: by 64-bit reference (Alpha and Integrity servers)

Time at which the timer expires. The daytim argument is the 64-bit address (on Alpha and Integrity server systems) of a quadword time value. A positive time value specifies an absolute time at which the timer expires; a negative time value specifies an offset (delta time) from the current time.

astadr


OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 64-bit reference (Alpha and Integrity servers)

AST service routine that is to execute when the timer expires. The astadr argument is the 64-bit address (on Alpha and Integrity server systems) of the procedure value of this routine. If you do not specify the value of astadr or specify it as 0 (the default), no AST routine executes.

The AST routine, if specified, executes at the access mode of the caller.

reqidt


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

Identification of the timer request. The reqidt argument is a longword value containing a number that uniquely identifies the timer request. If you do not specify reqidt, the value 0 is used.

To cancel a timer request, the identification of the timer request (as specified by reqidt in $SETIMR) is passed to the Cancel Timer ($CANTIM) service (as the reqidt argument).

If you want to cancel specific timer requests but not all timer requests, be sure to specify a nonzero value for reqidt in the $SETIMR call; $CANTIM interprets an identification value of 0 as a request to cancel all timer requests.

You can specify unique values for reqidt for each timer request or give the same value to related timer requests. This permits selective canceling of a single timer request, a group of related timer requests, or all timer requests.

If you specify the astadr argument in the $SETIMR call, the value specified by the reqidt argument is passed as a parameter to the AST routine. If the AST routine requires more than one parameter, specify an address for the value of reqidt; the AST routine can then interpret that address as the beginning of a list of parameters.

flags


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

Longword of bit flags for the set timer operation. Currently, only bit 0 is used for the flags argument. When the low bit (bit 0) is set, it indicates that this timer request should be in units of CPU time, rather than elapsed time. When bit 0 is clear (the default), the timer request is in units of elapsed time. The flags argument is optional.

Description

The Set Timer service sets the timer to expire at a specified time. When the timer expires, an event flag is set and (optionally) an AST routine executes. This service requires dynamic memory and executes at the access mode of the caller, as does the AST routine if one is specified.

Required Access or Privileges

None

Required Quota

This service uses the process's timer queue entries (TQELM) quota. If you specify an AST routine, the service uses the AST limit (ASTLM) quota of the process.

Related Services

$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The expiration time cannot be read by the caller.
SS$_EXQUOTA The process exceeded its quota for timer entries or its AST limit quota; or the system dynamic memory is insufficient for completing the request.
SS$_ILLEFC You specified an illegal event flag number.
SS$_INSFMEM The dynamic memory is insufficient for allocating a timer queue entry.
SS$_UNASEFC The process is not associated with the cluster containing the specified event flag.

$SETPRA

Establishes a routine to receive control after a power recovery is detected.

Format

SYS$SETPRA astadr ,[acmode]


C Prototype

int sys$setpra (int (*astadr)(__unknown_params), unsigned int acmode);


Arguments

astadr


OpenVMS usage: ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by reference

Power recovery AST routine to receive control when a power recovery is detected. The astadr argument is the address of this routine.

If you specify astadr as the value 0, an AST is not delivered to the process when a power recovery is detected.

The system passes one parameter to the specified AST routine. This parameter is a longword value containing the length of time that the power was off, expressed as the number of 1/100th-of-a-second intervals that have elapsed.

acmode


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

Access mode at which the power recovery AST routine is to execute. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines symbols for the access modes.

The most privileged access mode used is the access mode of the caller.


Description

The Set Power Recovery AST service establishes a routine to receive control after a power recovery is detected.

You can specify only one power recovery AST routine for a process. The AST entry point address is cleared at image exit.

The entry and exit conventions for the power recovery AST routine are the same as for all AST service routines.

Required Access or Privileges

None

Required Quota

One unit of quota is deducted from the process's ASTLM.

Related Services

$DCLAST, $SETAST

For more information, see the chapter about AST services in the HP OpenVMS Programming Concepts Manual.


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_EXQUOTA The process exceeded its quota for outstanding AST requests.


Previous Next Contents Index