Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

## $CREATE_RDB

> Initializes a rights database.

### Format

> SYS$CREATE_RDB [sysid]

### C Prototype

> int sys$create_rdb (struct _generic_64 *sysid);

### Argument

> #### sysid

> OpenVMS usage: | system_access_id
> type: | quadword (unsigned)
> access: | read only
> mechanism: | by reference

> System identification value associated with the rights database when $CREATE_RDB completes execution. The sysid argument is the address of a quadword containing the system identification value. If you omit sysid, the current system time in 64-bit format is used.

### Description

> The Create Rights Database service initializes a rights database. The database name is the file equated to the logical name RIGHTSLIST, which must be defined as a system logical name from executive mode. If the logical name does not exist, the database is created in SYS$COMMON:[SYSEXE] with the file name RIGHTSLIST.DAT. If the database already exists, $CREATE_RDB fails with the error RMS$_FEX.

> The rights database is created with an owner of [1,4] and a protection of (RWED, RWED, R).

> Required Access or Privileges

> Write access to the directory in which the file is being created is required.

> Required Quota

> None

> Related Services

> $ADD_HOLDER, $ADD_IDENT, $ASCTOID, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $GRANTID, $GET_SECURITY, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The sysid argument cannot be read by the caller.
> SS$_INSFMEM | The process dynamic memory is insufficient for opening the rights database.
> RMS$_FEX | A rights database already exists. To create a new one, you must explicitly delete or rename the old one.
> RMS$_PRV | The user does not have write access to SYS$SYSTEM.

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

## $CREATE_REGION_64 (Alpha Only)

> On Alpha systems, creates a virtual region within the process's private address space.

> This service accepts 64-bit addresses.

### Format

> SYS$CREATE_REGION_64 length_64 ,region_prot ,flags ,return_region_id_64 ,return_va_64 ,return_length_64 [,start_va_64]

### C Prototype

> int sys$create_region_64 ( unsigned __int64 length_64, unsigned int region_prot, unsigned int flags, struct _generic_64 *return_region_id, void *(*(return_va_64)), unsigned __int64 *return_length_64,...);

### Arguments

> #### length_64

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

> Length of the virtual region to be created. The length specified must be a multiple of CPU-specific pages. This length is fixed at the time the region is created.

> If the flag VA$M_SHARED_PTS is set, this length is rounded up to include an even multiple of CPU-specific pages mapped by a page table page.

> #### region_prot

> OpenVMS usage: | region_protection
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Region protection to be associated with the region to be created. The region_prot argument is a longword containing the create and owner mode.

> The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define the following symbols for valid combinations of create and owner modes:

> Symbol | Create and Owner Modes
> --- | ---
> VA$C_REGION_UCREATE_UOWN | User create mode and user owner mode
> VA$C_REGION_UCREATE_SOWN | User create mode and supervisor owner mode
> VA$C_REGION_UCREATE_EOWN | User create mode and executive owner mode
> VA$C_REGION_UCREATE_KOWN | User create mode and kernel owner mode
> VA$C_REGION_SCREATE_SOWN | Supervisor create mode and supervisor owner mode
> VA$C_REGION_SCREATE_EOWN | Supervisor create mode and executive owner mode
> VA$C_REGION_SCREATE_KOWN | Supervisor create mode and kernel owner mode
> VA$C_REGION_ECREATE_EOWN | Executive create mode and executive owner mode
> VA$C_REGION_ECREATE_KOWN | Executive create mode and kernel owner mode
> VA$C_REGION_KCREATE_KOWN | Kernel create mode and kernel owner mode

> For both create and owner mode, the $CREATE_REGION_64 service uses whichever of the following two access modes is least privileged:

> - Access mode specified by the acmode argument
> - Access mode of the caller

> A subsequent call to any system service that created address space within a region must be made from an access mode that is the same or more privileged than the create mode associated with the region.

> A subsequent call to $DELETE_REGION_64 to delete the region must be made from an access mode that is the same or more privileged than the owner mode associated with the region.

> All regions created by $CREATE_REGION_64 are automatically deleted when the image is run down on image exit.

> #### flags

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

> Flag mask specifying the characteristics of the region to be created. The flags argument is a longword bit vector in which each bit corresponds to a flag. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLB define a symbolic name for each flag. You construct the flags argument by performing a logical OR operation on the symbol names for all desired flags.

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

> Flag | Description
> --- | ---
> VA$M_DESCEND | Created region is a descending region; that is, allocation occurs toward decreasing virtual addresses. If VA$M_DESCEND is not specified, the region allocation occurs toward increasing virtual addresses.
> VA$M_SHARED_PTS | Created region requires the virtual address space created within it to be capable of using shared page tables. If this flag is not specified, the virtual address space created within the region is mapped by process-private page tables only. By default, the region does not allow the use of shared page tables.
> VA$M_P0_SPACE | Create region in P0 space. This flag cannot be set if VA$M_P1_SPACE is set.
> VA$M_P1_SPACE | Create region in P1 space. This flag cannot be set if VA$M_P0_SPACE is set.

> All other bits in the flags argument are reserved for future use by Compaq. The condition value SS$_IVREGFLG is returned if any undefined bits are set.

> #### return_region_id_64

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

> The region ID associated with the created region. The return_region_id_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the region ID.

> #### return_va_64

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

> The lowest process virtual address of the region. The return_va_64 argument is the 32- or 64-bit virtual address of a naturally aligned quadword into which the service returns the lowest virtual address of the region.

> If the flag VA$M_SHARED_PTS is set, the returned virtual address is aligned to a CPU-specific page table page boundary. If the global section mapped by this shared page table region is large enough that multiple page table pages are required to map the global section, the page tables themselves can be mapped with granularity hints; therefore, the alignment of the returned virtual address can be even greater than that of a single CPU-specific page table page boundary.

> #### return_length_64

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

> The length of the region actually created. 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 region in bytes.

> If the flag VA$M_SHARED_PTS is set, the returned length is the input length rounded up to an even multiple of bytes mapped by a single CPU-specific page table page.

> #### start_va_64

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

> The starting address for the created virtual region. The specified virtual address must be a CPU-specific page aligned address.

> If the start_va_64 argument is not specified or is specified as 0, the region can be created anywhere within the following address spaces:

> - P2 space (if the flags VA$M_P0_SPACE and VA$M_P1_SPACE are clear)
> - P0 space (if the flag VA$M_P0_SPACE is set and VA$M_P1_SPACE is clear)
> - P1 space (if the flag VA$M_P1_SPACE is set and VA$M_P0_SPACE is clear)

If the flag VA$M_SHARED_PTS is set and this argument is specified, the specified starting address must be aligned to a natural page table page boundary or an error is returned.

### Description

> The Create Virtual Region service allows a process to create a virtual region within its P0, P1, or P2 address space. Once a virtual region has been created, virtual address space can be created within it using the system services that accept a region identifier argument. Note that the virtual region is simply a reservation of virtual address space. No physical memory is occupied for a virtual region until virtual address space is created within the region.

> If the VA$M_SHARED_PTS flag is set in the flags argument, only memory-resident global sections can be mapped into the virtual region. The $CRMPSC_GDZRO_64 and $MGBLSC_64 system services are available for mapping to memory-resident global sections. If a memory-resident global section was not created with shared page tables, private page tables are used to map to the global section.

> If a memory-resident global section with shared page tables is mapped into a virtual region that does not have the shared page table attribute, the global section is mapped with process private page tables. Other address-space creation services (see Table SYS-3) are not allowed to create address space into a shared page table region because they have an implicit dependency on process-private page tables.

> Table SYS-3 Services That Do Not Accept Shared Page Table Regions
> Service | Description
> --- | ---
> $CRETVA[_64] | Adds a range of demand-zero allocation pages to a process's virtual address space for the execution of the current image. The new pages are added at the virtual address specified by the caller.
> $CRMPSC | Allows a process to create a private or global section and to map a section of its address space to the private or global section.
> $CRMPSC_FILE_64 | Allows a process to map a section of its address space to a specified portion of a file. This service maps a private disk file section.
> $CRMPSC_GFILE_64 | Allows a process to create a global disk file section and to map a section of its address space to the global section.
> $CRMPSC_GPFILE_64 | Allows a process to create a global page file section and to map a section of its address space to the global section.
> $CRMPSC_GPFN_64 | Allows a process to create a permanent global page frame section and to map a section of its address space to the global page frame section.
> $CRMPSC_PFN_64 | Allows a process to map a section of its address space to a specified physical address range represented by page frame numbers. This service creates and maps a private page frame section.
> $DELTVA | Deletes a specified number of pages from a process's virtual address space.
> $EXPREG_[64] 1 | Adds a specified number of demand-zero allocation pages to a process's virtual address space for the execution of the current image. Expansion occurs at the next free available address within the specified region.
> $MGBLSC | Establishes a correspondence between pages in the virtual address space of the process and the pages occupied by a global section.
> $MGBLSC_GPFN_64 | Establishes a correspondence between pages in the virtual address space of the process and the pages occupied by a global page frame section.

1$EXPREG can specify only the P0 or P1 region and thus cannot specify a shared page table region.

$CREATE_REGION_64 creates the virtual region on a CPU-specific page aligned boundary; however, if the VA$M_SHARED_PTS flag is set in the flags argument, the virtual region is created on a CPU-specific page table page aligned boundary.

Compaq recommends that you not specify the start_va_64 argument when creating a shared page table region due to the particular alignment that must prevail for virtual addresses created within the virtual region to exploit page table sharing. If the start_va_64 argument does not contain the proper alignment, $CREATE_REGION_64 returns SS$_VA_NOTPAGALGN.

If a starting virtual address must be specified for a shared page table region, use the following steps to compute a properly aligned start_va_64:

1. Determine the CPU-specific page size by using the $GETSYI system service and specifying the SYI$_PAGE_SIZE item code.
2. Determine the number of CPU-specific pages mapped by a single page table page by using the $GETSYI system service and specifying the SYI$_PTES_PER_PAGE item code.
3. Multiply the CPU-specific page size by the number of pages mapped by a page table page. The product represents the minimum virtual alignment required for a shared page table region. It also represents the number of bytes mapped by a single CPU-specific page table page. Assuming a system with an 8 kilobyte page size, the alignment of the start_va_64 argument must be an even multiple of 8,388,608 (8 megabytes). The virtual address, therefore, must have 23 low-order zero bits.
4. If the shared page tables are to be mapped with granularity hints (GH), the address computed in the previous step should to be adjusted to account for the granularity hint factor. The Alpha architecture provides three granularity hint factors: 8, 64, and 512 pages.

The virtual address alignment factors required for shared page table regions (and mappings using shared page tables) are more stringent than the simple CPU-specific page alignment. Global pages provide a level of data sharing in which the unit is a single CPU-specific page or, on today's systems, 8 kilobytes (KB). Shared page tables increase the level of sharing by an order of magnitude, such that the unit of sharing is a CPU-specific page table page or, on today's systems, 8 megabytes (MB); therefore, virtual regions that are to be used for shared page tables and mappings that use shared page tables require an alignment of at least 8 MB.

Table SYS-4 highlights the values $CREATE_REGION_64 returns for various region lengths. When the length_64 argument is not an even multiple of 8 MB, the returned length is rounded up to an even multiple of 8 MB. This must occur so that a shared page table region ends on an even CPU-specific page table page boundary.

Note The requirement for CPU-specific page table page multiples for shared page table regions does not imply that memory-resident global sections must also be sized at even CPU-specific page table page multiples. Memory-resident global sections must be specified in single CPU-specific page multiples as is the case for global page file sections.

The virtual alignment of the returned address is further biased by the ability to map the shared page tables with granularity hints. All values listed are based upon an 8 KB page size. All of the virtual addresses in the return_va_64 column accommodate the maximum GH factor for 8 KB page table pages.

Table SYS-4 Sample Returned Values from$CREATE_REGION_64
length_64 | return_va_64 | return_length_64 | Comments
--- | --- | --- | ---
1,048,576 (1 MB) | FFFFFFFB00800000 at least 23 zero bits | 8,388,608 (8 MB) | GH not possible for shared page table pages. Region occupies 1 page table page.
67,108,864 (64 MB) | FFFFFFFBFC000000 at least 26 zero bits | 67,108,864 (64 MB) | Returned VA accommodates GH factor of 8 for shared page table pages.
73,400,320 (70 MB) | FFFFFFFBF8000000 at least 26 zero bits | 75,497,472 (72 MB) | Returned VA accommodates GH factor of 8 for shared page table pages. Region occupies 9 page table pages. Only the first 8 can be mapped with GH.
1,073,741,824 (1 GB) | FFFFFFFBC0000000 at least 30 zero bits | 1,073,741,824 (1 GB) | Returned VA accommodates GH factor of 64 for shared page table pages. Region occupies 128 page table pages. In this case, there would be two GH regions, each containing 64 page table pages.

If the returned value of the service is not a successful condition value, a value is not returned in the memory locations pointed to by the return_region_id_64, return_va_64, or return_size_64 arguments.

Required Privileges

None

Required Quota

None

Related Services

$CRETVA_64, $CRMPSC_GDZRO, $CRMPSC_FILE_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64, $CRMPSC_GPFN_64, $CRMPSC_PFN_64, $DELETE_REGION_64, $DELTVA_64, $EXPREG_64, $GET_REGION_INFO, $MGBLSC_64, $MGBLSC_GPFN_64

### Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ACCVIO | The return_region_id_64 argument, the return_va_64 argument, or the return_length_64 argument cannot be written by the caller.
> SS$_IVREGFLG | One or more of the reserved bits in the flags argument is set, or an illegal combination of flags bits are set.
> SS$_LEN_NOTPAGMULT | The length_64 argument is not a multiple of CPU-specific pages.
> SS$_VASFULL | The process private address space is full, or no space is available in the process private address space for a region of the specified size.
> SS$_VA_IN_USE | A page in the specified virtual address range is within another virtual region or is otherwise inaccessible.
> SS$_VA_NOTPAGALGN | The start_va_64 argument is not CPU-specific page aligned; or, if the flag VA$M_SHARED_PTS is set, the start_va_64 argument is not CPU-specific page table page aligned.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_015.HTML