 |
OpenVMS System Services Reference Manual
You can pass a parameter to this routine by using the
astprm argument.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the resource name. The
acmode argument indicates the least privileged access
mode from which locks can be queued on the resource.
This argument does not affect the access mode associated with the lock
or its blocking and completion ASTs. The acmode
argument is a longword containing the access mode. The $PSLDEF macro
defines the following symbols for the four access modes:
| Symbol |
Access Mode |
|
PSL$C_KERNEL
|
Kernel
|
|
PSL$C_EXEC
|
Executive
|
|
PSL$C_SUPER
|
Supervisor
|
|
PSL$C_USER
|
User
|
The $ENQ service associates an access mode with the lock in the
following way:
- If you specified a parent lock (with the parid
argument), $ENQ uses the access mode associated with the parent lock
and ignores both the acmode argument and the caller's
access mode.
- If the lock has no parent lock (you did not specify the
parid argument or specified it as 0), $ENQ uses the
least privileged of the caller's access mode and the access mode
specified by the acmode argument. If you do not
specify the acmode argument, $ENQ uses the caller's
access mode.
rsdm_id
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Resource domain identification. The rsdm_id argument
is a longword specifying the resource domain association through which
a new lock is to be taken. This argument is ignored for lock
conversions and sublocks (parid is nonzero). Valid
resource domain identifiers are returned from the $SET_RESOURCE_DOMAIN
service, or by the constants RSDM$K_SYSTEM_RSDM_ID or
RSDM$K_PROCESS_RSDM_ID, which are defined by the $RSDMDEF macro in
STARLET.
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved by Compaq.
Description
The Enqueue Lock Request service queues a new lock or lock conversion
on a resource. The $ENQ service completes asynchronously; that is, it
returns to the caller after queuing the lock request without waiting
for the lock to be either granted or converted. For synchronous
completion, use the Enqueue Lock Request and Wait ($ENQW) service. The
$ENQW service is identical to the $ENQ service in every way except that
$ENQW returns to the caller when the lock is either granted or
converted.
The $ENQ service uses system dynamic memory for the creation of the
lock and resource blocks.
When $ENQ queues a lock request, it returns the status of the request
in R0 and writes the lock identification of the lock in the lock status
block. Then, when the lock request is granted, $ENQ writes the final
completion status in the lock status block, sets the event flag, and
calls the AST routine if this has been requested.
When $ENQW queues a lock request, it returns status in R0 and in the
lock status block when the lock has been either granted or converted.
Where applicable, it simultaneously sets the event flag and calls the
AST routine.
Invalidation of the Lock Value Block
In some situations, the lock value block can become invalid. In these
situations, $ENQ warns the caller by returning the condition value
SS$_VALNOTVALID in the lock status block, provided the caller has
specified the flag LCK$M_VALBLK in the flags argument.
The SS$_VALNOTVALID condition value is a warning message, not an error
message; therefore, the $ENQ service grants the requested lock and
returns this warning on all subsequent calls to $ENQ until either a new
lock value block is written to the lock database or the resource is
deleted. Resource deletion occurs when no locks are associated with the
resource.
The following events can cause the lock value block to become invalid:
- If any process holding a protected write or exclusive mode lock on
a resource is terminated abnormally, the lock value block becomes
invalid.
- If a node in an OpenVMS Cluster system fails and a process on that
node was holding (or might have been holding) a protected write or
exclusive mode lock on the resource, the lock value block becomes
invalid.
- If a process holding a protected write or exclusive mode lock on
the resource calls the Dequeue Lock Request ($DEQ) service to dequeue
this lock and specifies the flag LCK$M_INVVALBLK in the
flags argument, the lock value block maintained in the
lock database is marked invalid.
Required Access or Privileges
To queue a lock on a systemwide resource, the calling process must
either have SYSLCK privilege or be executing in executive or kernel
mode.
To specify a parent lock when queuing a lock, the access mode of the
caller must be equal to, or less privileged than, the access mode
associated with the parent lock.
To queue a lock conversion, the access mode associated with the lock
being converted must be equal to, or less privileged than, the access
mode of the calling process.
Required Quota
- Enqueue limit (ENQLM) quota
- AST limit (ASTLM) quota in lock conversion requests that you
specify either the astadr or blkast
argument
Related Services
$DEQ, $ENQW, $GETLKI, $GETLKIW, $SET_RESOURCE_DOMAIN
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the lock request was successfully
queued.
|
|
SS$_SYNCH
|
The service completed successfully; the LCK$M_SYNCSTS flag in the
flags argument was specified, and $ENQ was able to
grant the lock request immediately.
|
|
SS$_ACCVIO
|
The lock status block or the resource name cannot be read.
|
|
SS$_BADPARAM
|
You specified an invalid lock mode in the
lkmode argument.
|
|
SS$_CVTUNGRANT
|
You attempted a lock conversion on a lock that is not currently granted.
|
|
SS$_EXDEPTH
|
The limit of levels of sublocks has been exceeded.
|
|
SS$_EXENQLM
|
The process has exceeded its enqueue limit (ENQLM) quota.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for creating the necessary
data structures.
|
|
SS$_IVBUFLEN
|
The length of the resource name was either 0 or greater than 31.
|
|
SS$_IVLOCKID
|
You specified an invalid or nonexistent lock identification, or the
lock identified by the lock identification has an associated access
mode that is more privileged than the caller's, or the access mode of
the parent was less privileged than that of the caller.
|
|
SS$_NOLOCKID
|
No lock identification was available for the lock request.
|
|
SS$_NOSYSLCK
|
The LCK$M_SYSTEM flag in the
flags argument was specified, but the caller lacks the
necessary SYSLCK privilege.
|
|
SS$_NOTQUEUED
|
The lock request was not queued; the LCK$M_NOQUEUE flag in the
flags argument was specified, and $ENQ was not able to
grant the lock request immediately.
|
|
SS$_PARNOTGRANT
|
The parent lock specified in the
parid argument was not granted.
|
Condition Values Returned in the Lock Status Block
|
SS$_NORMAL
|
The service completed successfully; the lock was successfully granted
or converted.
|
|
SS$_ABORT
|
The lock was dequeued (by the $DEQ service) before $ENQ could grant the
lock.
|
|
SS$_CANCEL
|
The lock conversion request has been canceled and the lock has been
regranted at its previous lock mode. This condition value is returned
when $ENQ queues a lock conversion request, the request has not been
granted yet (it is in the conversion queue), and, in the interim, the
$DEQ service is called (with the LCK$M_CANCEL flag specified) to cancel
this lock conversion request. If the lock is granted before $DEQ can
cancel the conversion request, the call to $DEQ returns the condition
value SS$_CANCELGRANT, and the call to $ENQ returns SS$_NORMAL.
|
|
SS$_DEADLOCK
|
A deadlock was detected.
|
|
SS$_ILLRSDM
|
The operation attempted is not allowed on the resource. Use SHOW
SECURITY to verify the access allowed to the specified resource domain.
|
|
SS$_NODOMAIN
|
The RSDM_ID argument passed to the $ENQ call either does not correspond
to a valid resource domain for your process, or the system is not
running the audit server process.
|
|
SS$_VALNOTVALID
|
The lock value block is marked invalid. This warning message is
returned only if the caller has specified the flag LCK$M_VALBLK in the
flags argument. Note that the lock has been
successfully granted despite the return of this warning message. Refer
to the Description section for a complete discussion of lock value
block invalidation.
|
$ENQW
Queues a lock on a resource. The $ENQW service completes synchronously;
that is, it returns to the caller when the lock has been either granted
or converted. For asynchronous completion, use the Enqueue Lock Request
($ENQ) service; $ENQ returns to the caller after queuing the lock
request, without waiting for the lock to be either granted or
converted. In all other respects, $ENQW is identical to $ENQ. See the
$ENQ description for all other information about the $ENQW service.
For additional information about system service completion, see the
Synchronize ($SYNCH) service documentation.
The $ENQ, $ENQW, $DEQ, and $GETLKI services together provide the user
interface to the Lock Management facility.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ENQW [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid] ,[astadr]
,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]
C Prototype
int sys$enqw (unsigned int efn, unsigned int lkmode, struct _lksb
*lksb, unsigned int flags, void *resnam, unsigned int parid, void
(*astadr)(__unknown_params), unsigned __int64 astprm, void
(*blkast)(__unknown_params), unsigned int acmode, unsigned int
rsdm_id,...);
$ERAPAT
Generates a security erase pattern.
Format
SYS$ERAPAT [type] ,[count] ,[patadr]
C Prototype
int sys$erapat (int type, unsigned int count, unsigned int *patadr);
Arguments
type
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Type of storage to be written over with the erase pattern. The
type argument is a longword containing the type of
storage.
The three storage types, together with their symbolic names, are
defined by the $ERADEF macro and are listed in the following table:
| Storage Type |
Symbolic Name |
|
Main memory
|
ERA$K_MEMORY
|
|
Disk
|
ERA$K_DISK
|
|
Tape
|
ERA$K_TAPE
|
count
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of times that $ERAPAT has been called in a single security erase
operation. The count argument is a longword containing
the iteration count.
You should call the $ERAPAT service initially with the
count argument set to 1, the second time with the
count argument set to 2, and so on, until the status
code SS$_NOTRAN is returned.
patadr
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Security erase pattern to be written. The patadr
argument is the address of a longword into which the security erase
pattern is to be written.
Description
The Get Security Erase Pattern service generates a security erase
pattern that can be written into memory areas containing outdated but
sensitive data to make it unreadable. This service is used primarily by
the operating system, but it can also be used by users who want to
perform security erase operations on foreign disks.
You should call the $ERAPAT service iteratively until the completion
status SS$_NOTRAN is returned.
The following example demonstrates how to use the $ERAPAT service to
perform a security erase to a disk. Note that, after each call to
$ERAPAT, a test for the status SS$_NOTRAN is made. If SS$_NOTRAN has
not been returned, $QIO is called to write the pattern returned by
$ERAPAT onto the disk. After this write, $ERAPAT is called again and
the cycle is repeated until the code SS$_NOTRAN is returned, at which
point the security erase procedure is complete.
#include <ssdef.h>
#include <eradef.h>
#include <starlet.h>
/*
** This function takes a pointer to an array of integers and the
** number of elements in the array, and erases the memory used
** by the array. The function returns SS$_NORMAL upon success,
** or the error code from $ERAPAT for any failures.
*/
int ERASE_MEMORY(int *ptr, int items)
{
int loop, /* Loop counter for erasing buffer */
status, /* Status of system calls */
pattern, /* Place to store erase pattern */
count = 1; /* Count parameter for $ERAPAT */
/* Get pattern from $ERAPAT, erase memory, repeat... */
status = sys$erapat(ERA$K_MEMORY, count++, &pattern);
while (status == SS$_NORMAL)
{
for (loop = 0; loop < items; loop++)
ptr[loop] = pattern;
status = sys$erapat(ERA$K_MEMORY, count++, &pattern);
}
if (status == SS$_NOTRAN) /* Check for expected status */
status = SS$_NORMAL; /* Change to SS$_NORMAL if all's well */
return (status); /* Return success of failure indication */
}
|
Required Access or Privileges
None
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB,
$FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT,
$GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER,
$MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID,
$SET_SECURITY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; proceed with the next erase step.
|
|
SS$_NOTRAN
|
The service completed successfully; security erase completed.
|
|
SS$_ACCVIO
|
The
patadr argument cannot be written by the caller.
|
|
SS$_BADPARAM
|
The
type argument or
count argument is invalid.
|
$EXIT
Initiates image rundown when the current image in a process completes
execution. Control normally returns to the command interpreter.
Format
SYS$EXIT [code]
C Prototype
int sys$exit (unsigned int code);
Argument
code
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Longword value to be saved in the process header as the completion
status of the current image. If you do not specify this argument in a
macro call, a value of 1 is passed as the completion code for VAX MACRO
and VAX BLISS--32, and a value of 0 is passed for other languages. You
can test this value at the command level to provide conditional command
execution.
Description
The $EXIT service is unlike all other system services in that it does
not return status codes in R0 or anywhere else. The $EXIT service does
not return control to the caller; it performs an exit to the command
interpreter or causes the process to terminate if no command
interpreter is present.
Required Access or Privileges
None
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $FORCEX, $GETJPI, $GETJPIW, $HIBER,
$PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
$EXPREG
Adds a specified number of new virtual pages to a process's program
region or control region for the execution of the current image.
Expansion occurs at the current end of that region's virtual address
space.
Format
SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]
C Prototype
int sys$expreg (unsigned int pagcnt, struct _va_range *retadr, unsigned
int acmode, char region);
Arguments
pagcnt
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of pages (on VAX systems) or pagelets (on Alpha systems) to add
to the current end of the program or control region. The
pagcnt argument is a longword value containing this
number.
On Alpha systems, the specified value is rounded up to an even multiple
of the CPU-specific page size.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting and ending process virtual addresses of the pages that $EXPREG
has actually added. The retadr argument is the address
of a 2-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the newly added pages. The
acmode argument is a longword containing the access
mode.
The most privileged access mode used is the access mode of the caller.
The newly added pages are given the following protection: (1) read and
write access for access modes equal to or more privileged than the
access mode used in the call, and (2) no access for access modes less
privileged than that used in the call.
region
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number specifying which program region is to be expanded. The
region argument is a longword value. A value of 0 (the
default) specifies that the program region (P0 region) is to be
expanded. A value of 1 specifies that the control region (P1 region) is
to be expanded.
Description
The Expand Program/Control Region service adds a specified number of
new virtual pages to a process's program region or control region for
the execution of the current image. Expansion occurs at the current end
of that region's virtual address space.
The new pages, which were previously inaccessible to the process, are
created as demand-zero pages.
Because the bottom of the user stack is normally located at the end of
the control region, expanding the control region is equivalent to
expanding the user stack. The effect is to increase the available stack
space by the specified amount.
The starting address returned is always the first available page in the
designated region; therefore, the ending address is smaller than the
starting address when the control region is expanded and is larger than
the starting address when the program region is expanded.
If an error occurs while pages are being added, the
retadr argument (if specified) indicates the pages
that were successfully added before the error occurred. If no pages
were added, both longwords of the retadr argument
contain the value --1.
Required Access or Privileges
None
Required Quota
The process's paging file quota (PGFLQUOTA) must be sufficient to
accommodate the increased size of the virtual address space.
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $LCKPAG, $LKWSET,
$MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
Typically, the information returned in the location addressed by the
retadr argument (if specified) can be used as the
input range to the Delete Virtual Address Space ($DELTVA) service.
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The return address array cannot be written by the caller.
|
|
SS$_EXQUOTA
|
The process exceeded its paging file quota.
|
|
SS$_ILLPAGCNT
|
The specified page count was less than 1 or would cause the program or
control region to exceed its maximum size.
|
|
SS$_INSFWSL
|
The process's working set limit is not large enough to accommodate the
increased virtual address space.
|
|
SS$_VASFULL
|
The process's virtual address space is full. No space is available in
the process page table for the requested regions.
|
|
