HP OpenVMS Systems Documentation

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.

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.

$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.

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.

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.