HP OpenVMS System Services Reference Manual

All other bits in the flags argument are reserved for future use by HP. 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 the larger of a natural page table boundary or the largest possible page size used to map the section. If the alignment is less than a page table boundary, the $CREATE_REGION_64 service returns an error. If the alignment is less than the largest page size used in the section, an error might be returned when you attempt to map the section.

If you do not specify a starting address, OpenVMS automatically ensures correct alignment.

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-18) 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-18 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] ¹ 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.

**Table SYS-18 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] ¹	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.

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

HP 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:

Determine the CPU-specific page size by using the $GETSYI system service and specifying the SYI$_PAGE_SIZE item code.
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.
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.
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:
- On Alpha systems, granularity hints mean multiples of pages, regardless of page size. The multiples 8, 64, and 512 pages are architected.
- On I64 systems, OpenVMS initially supports page sizes of 64KB, 256KB, and 4MB instead of granularity hints. Additional pages sizes will be supported in the future.

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

**Table SYS-19 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.

$CREATE_UID

Generates a universally unique identifier (UID).

Format

SYS$CREATE_UID uid

C Prototype

int sys$create_uid (unsigned int uid [4]);

Arguments

uid

OpenVMS usage: uid

type: octaword (unsigned)

access: write only

mechanism: by reference

Address of an octaword in which the unique identifier is returned to the calling process.

Description

Generates a identifier that is unique across all computer systems.

Required Privileges

None

Required Quotas

None

Related Services

None

Condition Values Returned

SS$_NORMAL The request was successful.

SS$_ACCVIO An argument was not accessible to the caller.

$CREATE_USER_PROFILE

Returns an encoded security profile for the specified user.

Format

SYS$CREATE_USER_PROFILE usrnam ,[itmlst] ,[flags] ,usrpro ,usrprolen ,[contxt]

C Prototype

int sys$create_user_profile (void *usrnam, void *itmlst, unsigned int flags, void *usrpro, unsigned int *usrprolen, unsigned int *contxt);

Arguments

usrnam

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor

Name of the user whose security profile is to be returned. The usrnam argument is the address of a descriptor pointing to a text string containing the user name. The user name string can contain a maximum of 12 alphanumeric characters.
For more information about user names, see the HP OpenVMS Guide to System Security.
itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list specifying the portions of the user's security profile to be replaced or augmented.
The item list is a standard format item list. The following figure depicts the general format of an item descriptor. See the Item Codes section for a list of valid item codes for $CREATE_USER_PROFILE.

The following table defines the item descriptor fields:

Descriptor Field Definition

Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer from which the service is to read the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor.

Item code A word containing a user-supplied symbolic code specifying the item of information.

Buffer address A longword containing the user-supplied address of the buffer.

Return length address A longword that normally contains the user-supplied address of a word in which the service writes the length (in bytes) of the information it returned. This is not used by $CREATE_USER_PROFILE and should contain a 0.

Descriptor Field	Definition
Buffer length	A word containing a user-supplied integer specifying the length (in bytes) of the buffer from which the service is to read the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor.
Item code	A word containing a user-supplied symbolic code specifying the item of information.
Buffer address	A longword containing the user-supplied address of the buffer.
Return length address	A longword that normally contains the user-supplied address of a word in which the service writes the length (in bytes) of the information it returned. This is not used by $CREATE_USER_PROFILE and should contain a 0.

flags

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

The flags argument is used to control the behavior of the $CREATE_USER_PROFILE service. This argument does not accept ISS$ mask values; therefore, continue to use the CHP$ mask values for this argument.

The following table describes each flag:

Symbol Description

CHP$M_DEFCLASS By default, $CREATE_USER_PROFILE initializes the security profile with the user's maximum authorized classification. When this flag is set, the service initializes the security profile from the user's default classification instead. This flag is reserved to HP.

CHP$M_DEFPRIV By default, $CREATE_USER_PROFILE initializes the security profile with the user's authorized privilege mask. When this flag is set, the service initializes the security profile from the user's default privilege mask instead.

CHP$M_NOACCESS Instructs the service not to access the user authorization file (SYSUAF.DAT) or rights database (RIGHTSLIST.DAT) to build the security profile. This flag can be used as an optimization when all the information necessary to build the security profile is known to the caller.

Symbol	Description
CHP$M_DEFCLASS	By default, $CREATE_USER_PROFILE initializes the security profile with the user's maximum authorized classification. When this flag is set, the service initializes the security profile from the user's default classification instead. This flag is reserved to HP.
CHP$M_DEFPRIV	By default, $CREATE_USER_PROFILE initializes the security profile with the user's authorized privilege mask. When this flag is set, the service initializes the security profile from the user's default privilege mask instead.
CHP$M_NOACCESS	Instructs the service not to access the user authorization file (SYSUAF.DAT) or rights database (RIGHTSLIST.DAT) to build the security profile. This flag can be used as an optimization when all the information necessary to build the security profile is known to the caller.

usrpro

OpenVMS usage:	char_string
type:	opaque byte stream
access:	write only
mechanism:	by reference

Buffer to receive the security profile. The usrpro argument is the address of a buffer to receive the encoded security profile. If an address of 0 is specified, $CREATE_USER_PROFILE returns the size of the buffer needed in the usrprolen argument.

usrprolen

OpenVMS usage:	word
type:	word (unsigned)
access:	read/write
mechanism:	by reference

Word to receive the full size of the security profile. On input, the usrprolen argument specifies the length of the buffer pointed to by the usrpro argument. The usrprolen argument is the address of a word to which $CREATE_USER_PROFILE writes the actual length of the security profile. If the caller specifies a usrpro address of 0, $CREATE_USER_PROFILE returns the anticipated size, in bytes, of the buffer needed to hold the user's security profile in the usrprolen argument.

contxt

OpenVMS usage:	longword
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Longword used to maintain authorization file context. The contxt argument is the address of a longword to receive a $GETUAI context value. On the initial call, this longword should contain the value --1. On subsequent calls, the value of the contxt argument from the previous call should be passed back in.

Using the contxt argument keeps the UAF open across all calls, thereby improving the performance of the system on subsequent calls. To close the UAF, you must run down the image.

The resulting context value from a $CREATE_USER_PROFILE call can also be used as the input contxt argument to the $GETUAI system service, and vice versa.

Item Codes

CHP$_ADDRIGHTS
A rights list segment containing additional identifiers to be appended to the set of identifiers held by the user. A rights list segment is a list of quadword identifier/attributes pairs, each containing a longword identifier value, followed by a longword mask identifying the attributes of the holder. The buflen argument should be set to the total size, in bytes, of the rights list segment. The bufadr argument points to a descriptor that points to the first byte in the rights list segment (that is, the first byte of the first identifier value).
This item code can be repeated to add up to 256 additional rights list segments. If more than 256 identifiers are granted to the user, $CREATE_USER_PROFILE returns SS$_INSFMEM.
CHP$_CLASS
The classification to be associated with the created security profile. This item code is reserved to HP.
CHP$_PRIV
A quadword privilege mask specifying the user's privileges. The $PRVDEF macro defines the list of available privileges.
CHP$_UIC
A longword describing the user identification code (UIC).
ISS$_ACCOUNT
Variable-length buffer containing the account name. The maximum size of this buffer is 32 bytes.
ISS$_ADD_RIGHTS
A rights list segment containing additional identifiers to be appended to the set of identifiers held by the user. A rights list segment is a list of quadword identifier/attributes pairs, each containing a longword identifier value, followed by a longword mask identifying the attributes of the holder. The buflen argument should be set to the total size, in bytes, of the rights list segment. The bufadr argument points to a descriptor that points to the first byte in the rights list segment (that is, the first byte of the first identifier value).
This item code can be repeated to add up to 256 additional rights list segments. If more than 256 identifiers are granted to the user, $CREATE_USER_PROFILE returns SS$_INSFMEM.
ISS$_AUTHPRIV
Quadword containing the authorized privileges. See $PRVDEF macro for definitions.
ISS$_FLAGS
Longword containing user flags. The following flag is supported:
ISS$M_FLAG_SECAUDIT - Mandatory audit flag.
ISS$_MAXCLASS
Buffer containing the maximum classification. The maximum size of this buffer is CLS$K_LENGTH. This item code is reserved to HP. See the $CLSDEF macro for definitions.
ISS$_MINCLASS
Buffer containing the minimum classification. The maximum size of this buffer is CLS$K_LENGTH. This item code is reserved to HP. See the $CLSDEF macro for definitions.
ISS$_MODE
Longword containing the access mode. See $PSLDEF macro for definitions.
ISS$_PERMPRIV
Quadword containing the permanent privileges. See $PRVDEF macro for definitions.
ISS$_RIGHTS
Descriptor pointing to a vector of quadwords containing identifier/attribute pairs used to initialize the rights identifier list. See the $KGBDEF macro for definitions. Any identifiers specified by the ISS$_ADD_RIGHTS item code will be added to this list.
The format of this vector is as follows:

ISS$_UIC

A longword describing the user identification code (UIC).

ISS$_WORKCLASS

The classification to be associated with the created security profile. This item code is reserved to HP.

ISS$_WORKPRIV

A quadword privilege mask specifying the user's privileges. The $PRVDEF macro defines the list of available privileges.

Description

The Create User Profile service returns a security profile for a user. This profile can be generated in two ways:

If the caller does not specify the CHP$_NOACCESS flag in the flags argument, $CREATE_USER_PROFILE accesses the system authorization database (SYSUAF.DAT) or the rights database (RIGHTSLIST.DAT) for the specified user name and builds a representation of the privileges and rights granted to that user. The security profile is returned as an opaque byte stream.
$CREATE_USER_PROFILE returns a representation of the security profile that the user would have when logged in at the highest authorized classification with all authorized privileges enabled.
When the caller specifies the CHP$M_NOACCESS flag in the flags argument, $CREATE_USER_PROFILE creates a security profile without accessing the user authorization file (SYSUAF.DAT) or the rights database (RIGHTSLIST.DAT). When CHP$M_NOACCESS is specified, all of the information is obtained from the item list. The caller must supply the CHP$_PRIV and CHP$_UIC items. In addition, an address of 0 can be specified for the usrnam argument.

Previous Next Contents Index

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.

OpenVMS usage:	uid
type:	octaword (unsigned)
access:	write only
mechanism:	by reference

SS$_NORMAL	The request was successful.
SS$_ACCVIO	An argument was not accessible to the caller.

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference