 |
HP OpenVMS System Services Reference Manual
$NXTVOL
The Next Volume service allows you to process the next tape volume in a
multiple volume set. This service applies only to files on magnetic
tape volumes.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$OPEN
The Open service makes an existing file available for processing by
your program. The Open service specifies the type of record access to
be used and determines whether the file can be shared. The Open service
also performs an implicit Display service.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$PARSE
The Parse service analyzes the file specification string and fills in
various NAM block fields.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$PARSE_ACL
Parses the specified text string and converts it to the binary
representation for an access control entry (ACE).
Format
SYS$PARSE_ACL aclstr ,aclent ,[errpos] ,[accnam] ,[nullarg]
C Prototype
int sys$parse_acl (void *aclstr, void *aclent, unsigned short int
*errpos, void *accnam, int (*routin)(void));
Arguments
aclstr
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Formatted ACE that is parsed when $PARSE_ACL completes execution. The
aclstr argument is the address of a string descriptor
pointing to the text string to be parsed.
aclent
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Description of the ACE that is parsed when $PARSE_ACL completes
execution. The aclent argument is the address of a
descriptor pointing to the buffer in which the ACE is written. The
first byte of the buffer contains the length of the ACE; the second
byte contains a value that identifies the type of ACE, which in turn
defines the format of the ACE.
For information about the ACE types and their associated formats, see
$FORMAT_ACL system service documentation.
errpos
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters from aclstr processed by
$PARSE_ACL. The errpos argument is the address of a
word that receives the number of characters actually processed by the
service. If the service fails, this count points to the failing point
in the string.
accnam
| OpenVMS usage: |
access_bit_names |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Names of the bits in the access mask when $PARSE_ACL is executing. The
accnam argument is the address of an array of 32
quadword descriptors that define the names of the bits in the access
mask. Each element points to the name of a bit. The first element names
bit 0, the second element names bit 1, and so on.
You can call LIB$GET_ACCNAM to retrieve the access name table for the
class of object whose ACL is to be formatted. If you omit
accnam, the following names are used:
| Bit |
Name |
|
Bit 0
|
READ
|
|
Bit 1
|
WRITE
|
|
Bit 2
|
EXECUTE
|
|
Bit 3
|
DELETE
|
|
Bit 4
|
CONTROL
|
|
Bit 5
|
BIT_5
|
|
Bit 6
|
BIT_6
|
.
.
.
|
|
|
Bit 31
|
BIT_31
|
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved to HP.
Description
The Parse Access Control List Entry service parses the specified text
string and converts it to the binary representation for an access
control entry (ACE).
Required Access or Privileges
None
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB,
$ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL,
$FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC,
$MOD_HOLDER, $MOD_IDENT, $MTACCESS, $REM_HOLDER, $REM_IDENT, $REVOKID,
$SET_SECURITY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The string or its descriptor cannot be read by the caller; the buffer
descriptor cannot be read by the caller; the buffer cannot be written
by the caller; or the buffer is too small to hold the ACL entry.
|
|
SS$_IVACL
|
The format of the access control list entry is not valid.
|
|
SS$_NOSUCHID
|
The specified identifier does not exist in the rights database.
|
$PERM_DIS_ALIGN_FAULT_REPORT (Alpha and Integrity servers)
On Alpha and Integrity server systems, disables user process alignment
fault reporting.
Format
SYS$PERM_DIS_ALIGN_FAULT_REPORT
C Prototype
int sys$perm_dis_align_fault_report (void);
Arguments
None.
Description
The Disable Alignment Fault Reporting service disables user process
alignment fault reporting.
See the description of the $PERM_REPORT_ALIGN_FAULT service for an
example of a program that can be used to enable and disable user
process alignment fault reporting.
Required Access or Privileges
None
Required Quota
None
Related Services
$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,
$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT,
$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,
$STOP_SYS_ALIGN_FAULT_REPORT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
$PERM_REPORT_ALIGN_FAULT (Alpha and Integrity servers)
On Alpha and Integrity server systems, initializes user process
alignment fault reporting.
Format
SYS$PERM_REPORT_ALIGN_FAULT
C Prototype
int sys$perm_report_align_fault (void);
Arguments
None.
Description
The Report Alignment Fault service allows the user to permanently
enable user process alignment fault reporting for all subsequent images.
This service reports alignment faults only in exception mode. For more
information about reporting modes, see the $START_ALIGN_FAULT_REPORT
service.
Image alignment fault reporting takes precedence over process alignment
fault reporting; that is, if both image and process alignment fault
reporting are enabled, faults are reported to the image first.
Required Access or Privileges
None
Required Quota
None
Related Services
$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,
$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,
$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,
$STOP_SYS_ALIGN_FAULT_REPORT
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
Example
|
/**********************************************************************/
/* */
/* SET_ALIGN_REPORT.C */
/* */
/* This program can be used to permanently turn on and off */
/* alignment fault reporting for a process. After creating the */
/* executable, do: */
/* */
/* $ align :== $dir:set_align_report.exe */
/* $ align on */
/* $ run program ! will generate align faults on screen */
/* $ align off */
/* $ run program ! will not generate align faults */
/* */
/**********************************************************************/
#include <stdio>
#include <ctype>
#include <ssdef>
/* alignment fault reporting system services */
extern sys$perm_report_align_fault(),
sys$perm_dis_align_fault_report();
main(argc, argv)
int argc;
char *argv[];
{
int status;
/* check arguments */
if (argc < 2) {
printf ("Insufficient arguments\n");
return (40);
}
/* check if the argument is on or off */
if ((strcmp ("ON", argv[1]) == 0) || (strcmp ("on", argv[1]) == 0))
/* on, turn alignment fault reporting on for this process */
status = sys$perm_report_align_fault ();
else if ((strcmp ("OFF", argv[1]) == 0) || (strcmp ("off", argv[1]) == 0))
/* off, turn alignment fault reporting off for this process */
status = sys$perm_dis_align_fault_report ();
else
return (SS$_BADPARAM);
/* return status */
return (status);
}
|
This example shows a program that can be used to enable and disable
alignment fault reporting for a process.
$PERSONA_ASSUME (Alpha and Integrity servers)
On Alpha and Integrity server systems, allows an OpenVMS thread to
assume the identity of another persona.
Format
SYS$PERSONA_ASSUME persona ,[flags], [previous], [acmode]
C Prototype
int sys$persona_assume (unsigned int *persona, unsigned int flags,
unsigned int *previous, unsigned int acmode);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of a longword in which the persona identification handle is
expected.
If the value passed is ISS$C_ID_NATURAL, then the state of the calling
thread is returned to the natural persona.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Ignored.
previous
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the persona identification handle of
the currently active persona being replaced is written.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be considered when assuming a persona. The
acmode argument is a longword containing the access
mode.
The most privileged access mode used is the access mode of the caller.
Only equal or more privileged access modes can use this persona.
Description
This service establishes the specified persona as the active security
profile and returns the persona identification handle of the persona
that was active at the point in which the call to this service was made.
On image exit, the natural persona is assumed and all nonpermanent
personae are deleted.
The arguments are validated against the caller's mode, so an invalid
argument can cause an access violation to be signaled.
Required Access or Privileges
None
Required Quota
None
Related Services
$PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION,
$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully; the desired access is granted.
|
|
SS$_ACCVIO
|
Access violation.
|
|
SS$_INSFARG
|
Certain required arguments were not specified.
|
|
SS$_IVMODE
|
The caller cannot create a persona that is more privileged than the
caller.
|
|
SS$_NOPRIV
|
The operation requires IMPERSONATE privilege.
|
|
SS$_PERSONANONGRATA
|
Invalid persona argument.
|
$PERSONA_CLONE (Alpha and Integrity servers)
On Alpha and Integrity server systems, creates a copy of an existing
persona within the context of the current process. The service returns
the assigned persona identification for the new persona in the
persona argument. This persona can be assumed using
the $PERSONA_ASSUME service.
Format
SYS$PERSONA_CLONE persona ,[input]
C Prototype
int sys$persona_clone (unsigned int *persona, unsigned int *input);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the persona identification handle is
written.
input
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword containing the persona identification of the
persona to be cloned. If this argument is 0, null, or absent, the
currently active persona is cloned.
Description
The Clone Persona service creates a copy of an existing persona within
the context of the current process. The service returns the assigned
persona identification for the new persona in the
persona argument. This persona can be assumed using
the $PERSONA_ASSUME service.
On image exit, the natural persona is assumed and all nonpermanent
personae are deleted.
Required Access or Privileges
None
Required Quota
BYTLM
Related Services
$PERSONA_ASSUME, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION,
$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,
$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,
$PERSONA_QUERY, $PERSONA_RESERVE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
Access violation.
|
|
SS$_EXQUOTA
|
The caller lacks sufficient quota to allocate a new persona.
|
|
SS$_INSFMEM
|
Insufficient memory.
|
|
SS$_IVMODE
|
The caller cannot create a persona that is more privileged than the
caller.
|
|
SS$_PERSONANONGRATA
|
The persona ID supplied was invalid.
|
$PERSONA_CREATE (Alpha and Integrity servers)
On Alpha and Integrity server systems, creates a persona that can be
assumed using the $PERSONA_ASSUME service.
Format
SYS$PERSONA_CREATE persona ,[usrnam] ,[flags], [usrpro], [itmlst]
C Prototype
int sys$persona_create (unsigned int *persona, void *usrnam, unsigned
int flags, unsigned int *usrpro, unsigned int *itmlst);
Arguments
persona
| OpenVMS usage: |
persona |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of a longword into which the persona identification handle is
written.
usrnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length descriptor |
Name of the user to be impersonated. The usrnam
argument is the address of a descriptor pointing to a character string
containing the user name. The string can contain a maximum of 32
alphanumeric characters.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The $ISSDEF macro defines these codes:
- ISS$V_CREATE_AUTHPRIV - This bit is used to create a persona with
the privilege fields set to the authorized privileges of the specified
user.
- ISS$V_CREATE_DEFPRIV - This bit is used for backward compatibility
with the previous implementation of personae. This bit is accepted but
not processed, as it describes the default behavior of the service.
- ISS$V_NOACCESS - Tells $PERSONA_CREATE not to access the SYSUAF
file. Only valid in exec or kernel mode.
usrpro
| OpenVMS usage: |
char_string |
| type: |
opaque byte stream |
| access: |
read only |
| mechanism: |
by descriptor |
Buffer containing an encoded security profile. The
usrpro argument is the address of a descriptor
pointing to a buffer that contains encoded security profile data. This
profile can be created by calling the SYS$CREATE_USER_PROFILE system
service.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword |
| access: |
read only |
| mechanism: |
by reference |
Attributes describing modifications to the security profile. The
itmlst argument is the address of an item_list
defining changes to be made to the specified user profile.
This section lists the ISS$ item codes and definitions.
Item Codes
ISS$_WORKPRIV
$PERSONA_CREATE sets the working privileges for the new persona as a
quadword value.
ISS$_MODE
$PERSONA_CREATE sets the access mode of the new persona as a longword
value. The mode cannot be more privileged than that of the caller.
ISS$_FLAGS
$PERSONA_CREATE sets the flags field of the new persona as a longword
bit mask. The following bits are currently defined for this field:
- ISS$V_PERMANENT - Mark this persona as permanent. It will survive
image activations/deactivations.
- ISS$V_SECAUDIT - Always audit this persona's operations.
- ISS$V_DEBIT - Debit and credit the process BYTLM/BYTCNT for this
persona. (This flag is always set for user mode persona.)
ISS$_RIGHTS_INDEX
The index indicates into which rights chain the rights are placed.
Values for the index are: ISS$M_ENABLED_PERSONA, ISS$M_ENABLED_SYSTEM,
ISS$M_ENABLED_INSTALLED, ISS$M_ENABLED_SUBSYSTEM, and
ISS$M_ENABLED_TEMPORARY. All subsequent rights item packets use the
index until a new ISS$_RIGHTS_INDEX item changes the index. If a rights
index is not specified, the rights item packets will use the PERSONA
chain as the default. Rights item packets include: ISS$_AUTHRIGHTS,
ISS$_RIGHTS, ISS$_ADD_AUTHRIGHTS, and ISS$_ADD_RIGHTS.
ISS$_AUTHRIGHTS (Reserved for use by HP.)
$PERSONA_CREATE sets the user authorized rights of the new persona as a
list of quadword values. Any existing authorized rights will be
overwritten. By default, the rights will be placed in the PERSONA
rights chain. See ISS$_RIGHTS_INDEX for more information on specifying
different indexes.
ISS$_RIGHTS
$PERSONA_CREATE sets the user rights of the new persona as a list of
quadword (paired longword) values. Any existing authorized rights will
be overwritten. By default, the rights will be placed in the PERSONA
rights chain. See ISS$_RIGHTS_INDEX for more information on specifying
different indexes. The format of the list is the same as
ISS$_AUTHRIGHTS.
The format of the list is as follows:
ISS$_USERNAME
$PERSONA_CREATE sets the user name of the new persona as a 32-byte
character string.
ISS$_ACCOUNT
$PERSONA_CREATE sets the account of the new persona as a 32-byte
character string.
ISS$_NOAUDIT
$PERSONA_CREATE sets the No Audit field of the new persona as a
longword value.
ISS$_UIC
$PERSONA_CREATE sets the UIC of the new persona as a longword value.
ISS$_AUTHPRIV
$PERSONA_CREATE sets the authorized privileges for the new persona as a
quadword value.
ISS$_PERMPRIV
$PERSONA_CREATE sets the permanent privileges for the new persona as a
quadword value.
ISS$_IMAGE_WORKPRIV
$PERSONA_CREATE sets the image working privileges for the new persona
as a quadword value.
ISS$_ENABLED
$PERSONA_CREATE sets the Rights Enable field of the new persona as a
longword bit mask. These bits correspond to the indices of the
different rights chains. By setting the bit in the ENABLED field, the
corresponding rightslist chain will be enabled, and its rights will be
included in all rights checks. Valid bits are: ISS$V_ENABLED_PERSONA,
ISS$V_ENABLED_SUBSYSTEM, ISS$V_ENABLED_IMAGE, ISS$V_ENABLED_SYSTEM, and
ISS$V_ENABLED_TEMPORARY.
ISS$_ADD_AUTHRIGHTS
$PERSONA_CREATE adds the rights to the current list of authorized
rights. $PERSONA_CREATE expects the same format as that outlined in
ISS$_AUTHRIGHTS. By default, the rights will be placed in the PERSONA
rights chain. See ISS$_RIGHTS_INDEX for more information on specifying
different indexes.
ISS$_ADD_RIGHTS
$PERSONA_CREATE adds the rights to the current list of rights.
$PERSONA_CREATE expects the same format as that outlined in
ISS$_AUTHRIGHTS. By default, the rights will be placed in the PERSONA
rights chain. See ISS$_RIGHTS_INDEX for more information on specifying
different indexes.
Description
When you call this service, you can specify either the
usrnam or usrpro argument, but not
both. The required information specifying the OpenVMS user is read from
either the User Authorization File (UAF) and rights database or the
usrpro buffer and is stored in system memory. Any
modifications specified in the itmlst are then applied
to complete the new persona. A persona identification handle that
refers to the created persona is returned in the persona argument. This
service creates a default VMS extension for the persona.
It is possible to call $PERSONA_CREATE in any mode. To call
$PERSONA_CREATE in kernel mode, the calling sequence is different. Only
the usrpro argument is valid (usrnam
cannot be used because kernel mode access to the SYSUAF file is not
allowed), and it is necessary to set the PSB$M_NOACESS value in the
flags.
|
