 |
OpenVMS System Services Reference Manual
The security profile of the file is used to determine access to the
global section. For a global disk file section to allow write access to
the file during the mapping of the global section, the channel used to
open the file must allow write access to the file.
Required Privileges
To create a global section, the process must have the following
privileges:
- SYSGBL privilege to create a system global section (if flag
SEC$M_SYSGBL is set)
- PRMGBL privilege to create a permanent global section
Required Quota
None
Related Services
$CRMPSC, $CRMPSC_GFILE_64, $DGBLSC, $MGBLSC, $MGBLSC_64
Condition Values Returned
|
SS$_CREATED
|
The service completed successfully. The specified global section did
not previously exist and has been created.
|
|
SS$_ACCVIO
|
The
gs_name_64 argument or the
return_length_64 argument cannot be read by the caller.
|
|
SS$_CHANVIO
|
The specified channel was assigned from a more privileged access mode.
|
|
SS$_DUPLNAM
|
A global section of the same name already exists; a new global section
was not created.
|
|
SS$_ENDOFFILE
|
The
file_offset_64 argument specified is beyond the
logical end-of-file.
|
|
SS$_EXBYTLM
|
Process has exceeded the byte count quota; the system was unable to map
the requested file.
|
|
SS$_GPTFULL
|
There is no more room in the system global page table to set up page
table entries for the section.
|
|
SS$_GSDFULL
|
There is no more room in the system space allocated to maintain control
information for global sections.
|
|
SS$_IVCHAN
|
An invalid channel number was specified; the channel number specified
was 0 or a channel that is unassigned.
|
|
SS$_IVCHNLSEC
|
The channel number specified is currently active, or there are no files
opened on the specified channel.
|
|
SS$_IVIDENT
|
An invalid channel number was specified; the channel number specified
is larger than the number of channels available.
|
|
SS$_IVLOGNAM
|
The specified global section name has a length of 0 or has more than 43
characters.
|
|
SS$_IVLVEC
|
The specified section was not installed using the /PROTECT qualifier.
|
|
SS$_IVSECFLG
|
An invalid flag, a reserved flag, or an invalid combination of flags
was specified.
|
|
SS$_IVSECIDCTL
|
The match control field of the global section identification is invalid.
|
|
SS$_LEN_NOTBLKMULT
|
The
length_64 argument is not a multiple of virtual disk
blocks.
|
|
SS$_NOPRMGBL
|
The process does not have the privileges to create or delete a
permanent group global section (PRMGBL).
|
|
SS$_NOSYSGBL
|
The process does not have the privileges to create or delete a system
global section (SYSGBL).
|
|
SS$_NOTFILEDEV
|
The device is not a file-oriented, random-access, or directory device.
|
|
SS$_NOWRT
|
The file is read only, and the flag bit SEC$M_CRF is not set.
|
|
SS$_OFF_NOTBLKALGN
|
The
file_offset_64 argument is not a multiple of virtual
disk blocks.
|
|
SS$_SECTBLFUL
|
There are no entries available in the system global section table.
|
|
SS$_TOOMANYLNAM
|
The logical name translation of the
gs_name_64 argument exceeded the allowed depth of 10.
|
$CREATE_GPFILE (Alpha Only)
On Alpha systems, creates a permanent global page file section to which
processes can map.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GPFILE gs_name_64 ,ident_64 ,prot ,length_64 ,acmode ,flags
C Prototype
int sys$create_gpfile (void *gs_name_64, struct _secid *ident_64,
unsigned int prot, unsigned __int64 length_64, unsigned int acmode,
unsigned int flags);
Arguments
gs_name_64
| OpenVMS usage: |
section_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string
descriptor |
Name of the global section. The gs_name_64 argument is
the 32- or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
| OpenVMS usage: |
section_id |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Identification value specifying the version number of a global section.
The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-order 2
bits. Their meanings are as follows:
| Value |
Symbolic Name |
Match Criteria |
|
0
|
SEC$K_MATALL
|
Match all versions of the section.
|
|
1
|
SEC$K_MATEQU
|
Match only if major and minor identifications match.
|
|
2
|
SEC$K_MATLEQ
|
Match if the major identifications are equal and the minor
identification of the mapper is less than or equal to the minor
identification of the global section.
|
If you specify the ident_64 argument as 0, the version
number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24 bits
and a major identification in the high-order 8 bits. You can assign
values for these fields by installation convention to differentiate
versions of global sections. If no version number is specified when a
section is created, processes that specify a version number when
mapping cannot access the global section.
prot
| OpenVMS usage: |
file_protection |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Protection to be applied to the global page file section. The mask
contains four 4-bit fields. Bits are read from right to left in each
field. The following diagram depicts the mask:
Cleared bits indicate that read, write, execute, and delete access, in
that order, are granted to the particular category of user. Only read,
write, and execute access are meaningful for section protection. Delete
access bits are ignored. Read access also grants execute access for
those situations where execute access applies. If 0 is specified, read
access and write access are granted to all users.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length, in bytes, of the global page file section to be created. The
length_64 argument must be specified as a multiple of
the CPU-specific page size. A length of 0 cannot be specified.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode that is to be the owner of the pages created during the
mapping. 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
|
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the type of global section to be created as well
as its characteristics. The flags argument is a
longword bit vector in which each bit corresponds to a flag. The
$SECDEF macro and the SECDEF.H file 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_GPFILE service:
| Flag |
Description |
|
SEC$M_DZRO
|
Pages are demand-zero pages.
|
|
SEC$M_GBL
|
Pages form a global section. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_PAGFIL
|
Pages form a global page-file section. SEC$M_PAGFIL also implies
SEC$M_WRT and SEC$M_DZRO. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_PERM
|
Global section is permanent. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_SYSGBL
|
Pages form a system global section. By default, pages form a group
global section.
|
|
SEC$M_WRT
|
Pages form a read/write section. By default, this flag is always
present in this service and cannot be disabled.
|
All other bits in the flags argument are reserved for
future use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set.
Description
The Create Permanent Global Page File Section service allows a process
to create a permanent global page file section. Global page file
sections contain demand-zero allocation pages that are writable and
backed up by the system page file. All pages in the global page file
section are shared by all processes that map to the global section.
Required Privileges
To create a permanent global page file section, the process must have
the following privileges:
- SYSGBL privilege to create a system global section (if flag
SEC$M_SYSGBL is set)
- PRMGBL privilege to create a permanent global section
Required Quota
The systemwide number of global page file pages is limited by the
system parameter GBLPAGFIL.
Related Services
$CRMPSC, $CRMPSC_GPFILE_64, $DGBLSC, $MGBLSC, $MGBLSC_64
Condition Values Returned
|
SS$_CREATED
|
The service completed successfully. The specified global section did
not previously exist and has been created.
|
|
SS$_ACCVIO
|
The
gs_name_64 descriptor cannot be read by the caller.
|
|
SS$_DUPLNAM
|
A global section of the same name already exists; a new global section
was not created.
|
|
SS$_GPTFULL
|
There is no more room in the system global page table to set up page
table entries for the section.
|
|
SS$_GSDFULL
|
There is no more room in the system space allocated to maintain control
information for global sections.
|
|
SS$_IVLOGNAM
|
The specified global section name has a length of 0 or has more than 43
characters.
|
|
SS$_IVSECFLG
|
An invalid flag, a reserved flag, or an invalid combination of flags
was specified.
|
|
SS$_IVSECIDCTL
|
The match control field of the global section identification is invalid.
|
|
SS$_LEN_NOTPAGMULT
|
The
length_64 argument is not a multiple of CPU-specific
pages or was specified as 0.
|
|
SS$_NOPRMGBL
|
The process does not have the privileges to create or delete a
permanent group global section (PRMGBL).
|
|
SS$_NOSYSGBL
|
The process does not have the privileges to create or delete a system
global section (SYSGBL).
|
|
SS$_SECTBLFUL
|
There are no entries available in the system global section table.
|
|
SS$_TOOMANYLNAM
|
The logical name translation of the
gs_name_64 argument exceeded the allowed depth of 10.
|
$CREATE_GPFN (Alpha Only)
On Alpha systems, creates a permanent page frame section to which
processes can map.
This service accepts 64-bit addresses.
Format
SYS$CREATE_GPFN gs_name_64 ,ident_64 ,prot ,start_pfn ,page_count
,acmode ,flags
C Prototype
int sys$create_gpfn (void *gs_name_64, struct _secid *ident_64,
unsigned int prot, unsigned int start_pfn, unsigned int page_count,
unsigned int acmode, unsigned int flags);
Arguments
gs_name_64
| OpenVMS usage: |
section_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string
descriptor |
Name of the global section. The gs_name_64 argument is
the 32- or 64-bit virtual address of a naturally aligned 32- or 64-bit
string descriptor pointing to this name string.
ident_64
| OpenVMS usage: |
section_id |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Identification value specifying the version number of a global section.
The ident_64 argument is a quadword containing three
fields. The ident_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword that contains the
identification value.
The first longword specifies the matching criteria in its low-order two
bits.
The valid values, symbolic names by which they can be specified, and
their meanings are as follows:
| Value |
Symbolic Name |
Match Criteria |
|
0
|
SEC$K_MATALL
|
Match all versions of the section.
|
|
1
|
SEC$K_MATEQU
|
Match only if major and minor identifications match.
|
|
2
|
SEC$K_MATLEQ
|
Match if the major identifications are equal and the minor
identification of the mapper is less than or equal to the minor
identification of the global section.
|
If you specify the ident_64 argument as 0, the version
number and match control fields default to 0.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24 bits
and a major identification in the high-order 8 bits. You can assign
values for these fields by installation convention to differentiate
versions of global sections. If no version number is specified when a
section is created, processes that specify a version number when
mapping cannot access the global section.
prot
| OpenVMS usage: |
file_protection |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Protection to be applied to the global page frame section. The mask
contains four 4-bit fields. Bits are read from right to left in each
field. The following diagram depicts the mask:
Cleared bits indicate that read, write, execute, and delete access, in
that order, are granted to the particular category of user. Only read,
write, and execute access are meaningful for section protection. Delete
access bits are ignored. Read access also grants execute access for
those situations where execute access applies. If zero is specified,
read access and write access are granted to all users.
start_pfn
| OpenVMS usage: |
page frame number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The CPU-specific page frame number where the section begins in memory.
page_count
| OpenVMS usage: |
CPU-specific page count |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the page frame section in CPU-specific pages.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode that is to be the owner of the pages created during the
mapping. 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
|
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the characteristics of the page frame section to
be created. The flags argument is a longword bit
vector in which each bit corresponds to a flag. The $SECDEF macro and
the SECDEF.H file 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_GPFN service:
| Flag |
Description |
|
SEC$M_GBL
|
Pages form a global section. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_PERM
|
Global section is permanent. By default, this flag is always present in
this service and cannot be disabled.
|
|
SEC$M_PFNMAP
|
Pages form a page frame section. By default, this flag is always
present in this service and cannot be disabled.
|
|
SEC$M_SYSGBL
|
Pages form a system global page frame section. By default, pages form a
group global page frame section.
|
|
SEC$M_WRT
|
Pages form a read/write section. By default, pages form a read-only
section.
|
All other bits in the flags argument are reserved for
future use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an illegal
combination of flags is set.
Description
The Create Permanent Global Page Frame Section service allows a process
to create a global page frame section. All global page frame sections
are permanent. Pages mapped to a global page frame section are not
included in or charged against the process's working set; they are
always valid.
Do not lock these pages in the working set by using $LKWSET_64; this
can result in a machine check if they are in I/O space.
Required Privileges
To create a permanent global page frame section, the process must have
the following privileges:
- SYSGBL privilege to create a system global section (if flag
SEC$M_SYSGBL is set)
- PRMGBL privilege to create a permanent global section
- PFNMAP privilege to create a page frame section
Required Quota
None
Related Services
$CRMPSC, $CRMPSC_GPFN_64, $DGBLSC, $MGBLSC, $MGBLSC_GPFN_64
Condition Values Returned
|
SS$_CREATED
|
The service completed successfully. The specified global section did
not previously exist and has been created.
|
|
SS$_ACCVIO
|
The
gs_name_64 argument cannot be read by the caller.
|
|
SS$_DUPLNAM
|
A global section of the same name already exists; a new global section
was not created.
|
|
SS$_GPTFULL
|
There is no more room in the system global page table to set up page
table entries for the section.
|
|
SS$_GSDFULL
|
There is no more room in the system space allocated to maintain control
information for global sections.
|
|
SS$_IVLOGNAM
|
The specified global section name has a length of 0 or has more than 43
characters.
|
|
SS$_IVSECFLG
|
An invalid flag, a reserved flag, or an invalid combination of flags
was specified.
|
|
SS$_IVSECIDCTL
|
The match control field of the global section identification is invalid.
|
|
SS$_NOPRMGBL
|
The process does not have the privileges to create or delete a
permanent group global section (PRMGBL).
|
|
SS$_NOSYSGBL
|
The process does not have the privileges to create or delete a system
global section (SYSGBL).
|
|
SS$_TOOMANYLNAM
|
The logical name translation of the
gs_name_64 argument exceeded the allowed depth of 10.
|
|
