 |
HP OpenVMS System Services Reference Manual
$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.
|
|
