Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $IO_PERFORMW (Alpha Only)

> On Alpha systems, starts a Fast I/O operation. The $IO_PERFORMW service completes synchronously; that is, it returns to the caller after performing the Fast I/O operation.

> In all other respects, $IO_PERFORMW is identical to $IO_PERFORM. For all other information about the IO_PERFORMW service, refer to the description of $IO_PERFORM in this manual.

### Format

> SYS$IO_PERFORMW fandle ,chan ,iosadr ,bufadr ,buflen ,devdata

### C Prototype

> int sys$io_performw (unsigned __int64 fandl, unsigned short int chan, struct _iosa *iosadr, void *bufadr, unsigned __int64 buflen, unsigned __int64 devdata);

## $IO_SETUP (Alpha Only)

> On Alpha systems, allocates resources for Fast I/O.

> This service accepts 64-bit addresses.

### Format

> SYS$IO_SETUP func ,bufobj ,iosobj ,astadr ,flags ,return_fandle

### C Prototype

> int sys$io_setup (unsigned int func, struct _generic_64 *bufobj, struct _generic_64 *iosobj, void (*astadr)(struct _iosa *), unsigned int flags, unsigned __int64 *return_fandle);

### Arguments

> #### func

> OpenVMS usage: | function_code
> type: | longword
> access: | read only
> mechanism: | by value

> I/O function code. Must be one of the following:
> - IO$_READVBLK
> - IO$_WRITEVBLK
> - IO$_READLBLK
> - IO$_WRITELBLK

> Various function modifiers are supported, depending on the device and driver. Disk drivers support IO$M_NOVCACHE and IO$M_DATACHECK. Some tape devices support IO$M_REVERSE. Illegal modifiers are detected by the $IO_PERFORM(W) service.

> #### bufobj

> OpenVMS usage: | buffer object
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by 32- or 64-bit reference

> Handle describing the buffer object that contains the user's buffer. This identifier cannot be 0.

> #### iosobj

> OpenVMS usage: | object handle
> type: | vector longword (unsigned)
> access: | read only
> mechanism: | by 32- or 64-bit reference

> Buffer object handle describing the buffer object that contains the I/O Status Area (IOSA). This might or might not be the same identifier as the bufobj argument. This identifier cannot be 0.

> #### astadr

> OpenVMS usage: | ast_procedure
> type: | procedure value
> access: | read only
> mechanism: | by 32- or 64-bit reference

> Completion AST routine address (0, if none). There is no AST parameter argument. When the AST routine is called, the AST parameter will be the address of the IOSA for the operation. Applications can store data in the IOSA at offset IOSA$IH_CONTEXT.

> #### flags

> OpenVMS usage: | mask_longword
> type: | 64-bit integer (unsigned)
> access: | read only
> mechanism: | by value

> Flag mask. The flags argument is a bit vector in which each bit corresponds to a flag. Flags are defined in the module IOSADEF.

> The following table describes the flags that are valid for the $IO_SETUP service:

> Flag | Description
> --- | ---
> FIO$M_EXPEDITE | This is a high priority I/O; that is, it is to be given preferential treatment by the I/O subsystem. Use of this bit requires ALTPRI or PHY_IO privilege.
> FIO$M_AST_NOFLOAT | The AST procedure does not use, or call any procedure that uses, any floating-point registers. This is a performance option. If set, AST delivery will neither save nor restore floating-point registers. Caution: Use of floating-point registers when FIO$M_AST_NOFLOAT has been specified can cause unpredictable, difficult to detect, error conditions.

> All other bits in the flags argument are reserved for future use by Compaq and should be specified as 0.

> #### return_fandle

> OpenVMS usage: | fandle
> type: | 64-bit integer (unsigned)
> access: | write only
> mechanism: | by 32- or 64-bit reference

> Address of an aligned quadword to receive the fandle for this I/O operation.

### Description

> The Set Up Fast I/O system service allocates and initializes a number of internal objects based on the parameters supplied. Because these objects are then ready for use when a subsequent $IO_PERFORM or $IO_PERFORMW is issued, the I/O operation will require less CPU time and fewer multiprocessor steps.

> Required Privileges

> If you use the flags argument FIO$M_EXPEDITE, a process must have ALTPRI or PHY_IO privilege.

> Required Quota

> Byte count

> Related Services

> $IO_CLEANUP, $IO_PERFORM(W)

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The fandle does not have 8 bytes of writability, or the two buffer objects do not have 8 bytes of readability each.
> SS$_INSFMEM | There is no pool available from which to create a fandle vector, or the fandle vector is already full and an attempted expansion failed.
> SS$_ILLIOFUNC | The function code is not valid.
> SS$_ILLMODIFIER | The I/O function modifier is not permitted.
> SS$_UNALIGNED | The I/O Status Area (IOSA) or data buffer is not aligned on a quadword boundary.

## $LCKPAG

> Locks a page or range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and in this sense are locked in the working set as well.

### Format

> SYS$LCKPAG inadr ,[retadr] ,[acmode]

### C Prototype

> int sys$lckpag (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode);

### 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 to be locked. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.

> On VAX systems, if the starting and ending virtual addresses are the same, a single page is locked.

> #### retadr

> OpenVMS usage: | address_range
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference

> Starting and ending process virtual addresses of the pages that $LCKPAG actually locked. 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 pages to be locked. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the four access modes.

> The most privileged access mode used is the access mode of the caller. For the $LCKPAG service to complete successfully, the resultant access mode must be equal to or more privileged than the access mode already associated with the pages to be locked.

### Description

> The Lock Pages in Memory service locks a page or range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and in this sense are locked in the working set as well.

> If more than one page is being locked and you need to determine specifically which pages were previously locked, the pages should be locked one at a time.

> If an error occurs while the $LCKPAG service is locking pages, the return array, if requested, indicates the pages that were successfully locked before the error occurred. If no pages are locked, both longwords in the return address array contain the value --1.

> On Alpha systems, if you are attempting to lock executable code, you should issue multiple $LCKPAG calls: one to lock the code pages and others to lock the linkage section references into these pages.

> Required Access or Privileges

> The calling process must have PSWAPM privilege to lock pages into memory.

> Required Quota

> None

> Related Services

> You can unlock pages locked in memory with the Unlock Pages from Memory ($ULKPAG) service. Locked pages are automatically unlocked at image exit.

> For more information, refer to the chapter on memory management in the OpenVMS Programming Concepts Manual.

### Condition Values Returned

> SS$_WASCLR | The service completed successfully. All of the specified pages were previously unlocked.
> SS$_WASSET | The service completed successfully. At least one of the specified pages was previously locked.
> SS$_ACCVIO | The input array cannot be read; the output array cannot be written; the page in the specified range is inaccessible or nonexistent; or an attempt to lock pages was made by a caller whose access mode is less privileged than the access mode associated with the pages.
> SS$_LCKPAGFUL | The system-defined maximum limit on the number of pages that can be locked in memory has been reached.
> SS$_LDWSETFUL | The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
> SS$_NOPRIV | The process does not have the privilege to lock pages in memory.
> SS$_PAGOWNVIO | The pages could not be locked because the access mode associated with the call to $LCKPAG was less privileged than the access mode associated with the pages that were to be locked.

## $LCKPAG_64 (Alpha Only)

> On Alpha systems, locks a range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and, in this sense, are locked in the working set as well.

> This service accepts 64-bit addresses.

### Format

> SYS$LCKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64

### C Prototype

> int sys$lckpag_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, void *(*(return_va_64)), unsigned __int64 *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 pages to be locked. The specified virtual address will be rounded down to a CPU-specific page boundary.

> #### length_64

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

> Length of the virtual address space to be locked. 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 pages to be locked. 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. For the $LCKPAG_64 service to complete successfully, the resultant access mode must be equal to or more privileged than the access mode already associated with the pages to be locked.

> #### 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 pages locked in memory. 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 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the length of the virtual address range locked in bytes.

### Description

> The Lock Pages in Memory service locks a range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and, in this sense, are locked in the working set as well.

> 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 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 locked before the error occurred. If no pages were locked, 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

> A process must have PSWAPM privilege to call the $LCKPAG_64 service.

> Required Quota

> None

> Related Services

> $LCKPAG, $ULKPAG, $ULKPAG_64

### Condition Values Returned

> SS$_WASCLR | The service completed successfully. All of the specified pages were previously unlocked.
> SS$_WASSET | The service completed successfully. At least one of the specified pages was previously locked in the working set.
> SS$_ACCVIO | The return_va_64 argument or the return_length_64 argument cannot be written by the caller, or an attempt was made to lock pages by a caller whose access mode is less privileged than the access mode associated with the pages.
> SS$_LCKPAGFUL | The system-defined maximum limit on the number of pages that can be locked in memory has been reached.
> SS$_LKWSETFUL | The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
> SS$_NOPSWAPM | The process does not have the privilege to lock pages in memory.
> SS$_PAGOWNVIO | The pages could not be locked because the access mode associated with the call to $LCKPAG_64 was less privileged than the access mode associated with the pages that were to be locked.

## $LKWSET

> Locks a range of pages in the working set; if the pages are not already in the working set, it brings them in and locks them. A page locked in the working set does not become a candidate for replacement.

### Format

> SYS$LKWSET inadr ,[retadr] ,[acmode]

### C Prototype

> int sys$lkwset ( struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode);

### 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 to be locked in the working set. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.

> On VAX systems, if the starting and ending virtual addresses are the same, a single page is locked.

> #### retadr

> OpenVMS usage: | address_range
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference

> Starting and ending process virtual addresses of the range of pages actually locked by $LCKWSET. 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 pages to be locked. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the four access modes.

> The most privileged access mode used is the access mode of the caller. For the $LKWSET service to complete successfully, the resultant access mode must be equal to or more privileged than the access mode already associated with the pages to be locked.

### Description

> The Lock Pages in Working Set service locks a range of pages in the working set; if the pages are not already in the working set, it brings them in and locks them. A page locked in the working set does not become a candidate for replacement.

> If more than one page is being locked and you need to determine specifically which pages were previously locked, the pages should be locked one at a time.

> If an error occurs while the $LKWSET service is locking pages, the return array, if requested, indicates the pages that were successfully locked before the error occurred. If no pages are locked, both longwords in the return address array contain the value --1.

> Global pages with write access cannot be locked into the working set.

> On Alpha systems, if you are attempting to lock executable code, you should issue multiple $LKWSET calls: one to lock the code pages and others to lock the linkage section references into these pages.

> Required Access or Privileges

> None

> Required Quota

> None

> Related Services

> You can unlock pages locked in the working set with the Unlock Page from Working Set ($ULWSET) service.

> For more information, refer to the chapter on memory management in the OpenVMS Programming Concepts Manual.

### Condition Values Returned

> SS$_WASCLR | The service completed successfully. All of the specified pages were previously unlocked.
> SS$_WASSET | The service completed successfully. At least one of the specified pages was previously locked in the working set.
> SS$_ACCVIO | The input address array cannot be read; the output address array cannot be written; a page in the specified range is inaccessible or nonexistent; or an attempt was made to lock pages by a caller whose access mode is less privileged than the access mode associated with the pages.
> SS$_LKWSETFUL | The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
> SS$_NOPRIV | A page in the specified range is in the system address space, or a global page with write access was specified.
> SS$_PAGOWNVIO | The pages could not be locked because the access mode associated with the call to $LKWSET was less privileged than the access mode associated with the pages that were to be locked.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_066.HTML