 |
HP OpenVMS System Services Reference Manual
$REVOKID
Removes the specified identifier from the rights list of the process or
the system. If the identifier is listed as a holder of any other
identifier, the appropriate holder records are also deleted.
Format
SYS$REVOKID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]
C Prototype
int sys$revokid (unsigned int *pidadr, void *prcnam, struct _generic_64
*id, void *name, unsigned int *prvatr, unsigned int segment);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) number of the process affected when
$REVOKID completes execution. The pidadr argument is
the address of a longword containing the PID of the process to be
affected. You use --1 to indicate the system rights list. When
pidadr is passed, it is also returned; therefore, you
must pass it as a variable rather than a constant.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Process name on which $REVOKID operates. The prcnam
argument is the address of a character string descriptor containing the
process name. The maximum length of the name is 15 characters. Because
the UIC group number is interpreted as part of the process name, you
must use pidadr to specify the rights list of a
process in a different group.
id
| OpenVMS usage: |
rights_id |
| type: |
quadword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Identifier and attributes to be removed when $REVOKID completes
execution. The id argument is the address of a
quadword containing the binary identifier code to be removed in the
first longword and the attributes in the second longword.
Symbol values are offsets to the bits within the longword. You can also
obtain the values as masks with the appropriate bit set using the
prefix KGB$M rather than KGB$V. The following symbols for each bit
position are defined in the system macro library ($KGBDEF):
| Bit Position |
Meaning When Set |
|
KGB$V_DYNAMIC
|
Allows unprivileged holders of the identifier to remove it from or add
it to the process rights database by using the DCL command SET
RIGHTS_LIST.
|
|
KGB$V_NOACCESS
|
Makes any access rights of the identifier null and void. This attribute
is intended as a modifier for a resource identifier or the Subsystem
attribute.
|
|
KGB$V_RESOURCE
|
Allows holders of an identifier to charge disk space to the identifier.
It is used only for file objects.
|
|
KGB$V_SUBSYSTEM
|
Allows holders of the identifier to create and maintain protected
subsystems by assigning the Subsystem ACE to the application images in
the subsystem.
|
You must specify either id or name.
Because the id argument is returned as well as passed
if you specify name, you must pass it as a variable
rather than a constant in this case.
name
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the identifier removed when $REVOKID completes execution. The
name argument is the address of a descriptor pointing
to the name of the identifier.
prvatr
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Attributes of the deleted identifier. The prvatr
argument is the address of a longword used to store the attributes of
the identifier.
Description
The Revoke Identifier from Process service removes the specified
identifier from the rights list of the process or the system. If the
identifier is listed as a holder of any other identifier, the
appropriate holder records are also deleted.
The result of passing the pidadr or the
prcnam argument, or both, to $REVOKID is summarized in
the following table.
Note that a value of 0 in either of the following tables indicates that
the contents of the address specified by the argument is the value 0.
The word omitted indicates that the argument was not supplied.
| prcnam |
pidadr |
Result |
|
Omitted
|
Omitted
|
Current process ID is used; process ID is not returned.
|
|
Omitted
|
0
|
Current process ID is used; process ID is returned.
|
|
Omitted
|
Specified
|
Specified process ID is used.
|
|
Specified
|
Omitted
|
Specified process name is used; process ID is not returned.
|
|
Specified
|
0
|
Specified process name is used; process ID is returned.
|
|
Specified
|
Specified
|
Specified process ID is used and process name is ignored.
|
The result of passing either the name or the
id argument, or both, to SYS$REVOKID is summarized in
the following table:
| name |
id |
Result |
|
Omitted
|
Omitted
|
Illegal. The INSFARG condition value is returned.
|
|
Omitted
|
Specified
|
Specified identifier value is used.
|
|
Specified
|
Omitted
|
Specified identifier name is used; identifier value is not returned.
|
|
Specified
|
0
|
Specified identifier name is used; identifier value is returned.
|
|
Specified
|
Specified
|
Specified identifier value is used and identifier name is ignored.
|
Because the Revoke Identifier from Process service removes the
specified identifier from the rights list of the process or the system,
this service is meant for use by a privileged subsystem to alter the
access rights profile of a user, based on installation policy. It is
not meant for use by the general system user.
Required Access or Privileges
You need CMKRNL privilege to invoke this service. In addition, you need
GROUP privilege to modify the rights list of a process in the same
group as the calling process (unless the process has the same UIC as
the calling process). You need WORLD privilege to modify the rights
list of a process outside the caller's group. You need SYSNAM privilege
to modify the system rights list.
Required Quota
None
Related Services
$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD,
$FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER, $MOD_IDENT,
$REM_HOLDER, $REM_IDENT
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully; the rights list did not contain the
specified identifier.
|
|
SS$_WASSET
|
The service completed successfully; the rights list already held the
specified identifier.
|
|
SS$_ACCVIO
|
The
pidadr argument cannot be read or written;
prcnam cannot be read;
id cannot be read or written;
name cannot be read; or
prvatr cannot be written.
|
|
SS$_INSFARG
|
You did not specify either the
id or the
name argument.
|
|
SS$_INSFMEM
|
The process dynamic memory is insufficient for opening the rights
database.
|
|
SS$_IVIDENT
|
The specified identifier name is invalid; the identifier name is longer
than 31 characters, contains an illegal character, or does not contain
at least one nonnumeric character.
|
|
SS$_IVLOGNAM
|
You specified an invalid process name.
|
|
SS$_NONEXPR
|
You specified a nonexistent process.
|
|
SS$_NOPRIV
|
The caller does not have CMKRNL privilege or is not running in
executive or kernel mode; or the caller lacks GROUP, WORLD, or SYSNAM
privilege as required.
|
|
SS$_NOSUCHID
|
The specified identifier name does not exist in the rights database.
Note that the binary identifier, if given, is not validated against the
rights database.
|
|
SS$_NOSYSNAM
|
The operation requires SYSNAM privilege.
|
|
SS$_RIGHTSFULL
|
The rights list of the process or system is full.
|
|
RMS$_PRV
|
The user does not have read access to the rights database.
|
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.
$REWIND
The Rewind service sets the context of a record stream to the first
record in the file. RMS alters the context of the next record to
indicate the first record as being the next record.
Refer to the OpenVMS Record Management Services Reference Manual for additional information about this
service.
$RMSRUNDWN
Closes all files opened by OpenVMS RMS for the image or process and
halts I/O activity. This routine performs a $CLOSE service for each
file opened for processing.
Format
SYS$RMSRUNDWN buf-addr ,type-value
C Prototype
int sys$rmsrundwn (void *buf-addr, unsigned char *type-value);
Arguments
buf-addr
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor |
A descriptor pointing to a 22-byte buffer that is to receive the device
identification (16 bytes) and the file identification (6 bytes) of an
improperly closed output file. The buf-addr argument
is the address of the descriptor that points to the buffer.
type-value
| OpenVMS usage: |
byte_unsigned |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by value |
A single byte code that specifies the type of I/O rundown to be
performed. The type-value argument is the actual value
used.
This type of code has the following values and meanings:
|
0
|
Rundown of image and indirect I/O for process permanent files.
|
|
1
|
Rundown of image and process permanent files. The caller's mode must
not be user.
|
|
2
|
Abort RMS I/O. The caller's mode must be either executive or kernel
(the system calls the I/O rundown control routine with this argument
for process deletion).
|
Description
The RMS Rundown service closes all files opened by OpenVMS RMS for the
image or process and halts I/O activity. This routine performs a $CLOSE
service for each file opened for processing. In addition to closing all
files and terminating I/O activity, the I/O rundown control routine
releases all locks held on records in shared files, clears buffers, and
returns other resources allocated for file processing. You should
continue to call the rundown control routine until you receive the
success completion status code of RMS$_NORMAL.
Note that, prior to the execution of the $CLOSE service, the rundown
control routine cancels all outstanding file operations specified in a
File Access Block (FAB) or any QIO requests related to file operations
(an Open, Create, or Extend service, for example). It also cancels any
read/write requests to nondisk devices such as terminals or mailboxes
prior to the execution of the $CLOSE service, resulting in possible
loss of data. All read/write requests of disk I/O buffers, however, are
allowed to complete, which guarantees that none of the data written to
disk files will be lost.
There is no predefined macro of the form $RMSRUNDWN_G or $RMSRUNDWN_S
to call this service.
Required Access or Privileges
None
Required Quota
None
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CLOSE, $CREMBX,
$DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW,
$GETMSG, $GETQUI, $GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW,
$SETDDIR, $SETDFPROT, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
Condition Values Returned
|
RMS$_NORMAL
|
The service completed successfully.
|
|
RMS$_CCF
|
The I/O rundown routine cannot close the file.
|
|
RMS$_IAL
|
The argument list is invalid. An output file could not be closed
successfully, and the user buffer could not be written.
|
$RPCC_64 (Alpha and I64)
On Alpha and I64 systems, returns a 64-bit, process-based,
high-resolution time counter.
Format
SYS$RPCC_64
C Prototype
uint64 sys$rpcc_64 ();
Description
On Alpha and I64 systems, returns a 64-bit long version of the current
process cycle counter.
On Alpha systems, this service must be called at least once within each
wrap period of the least significant 32 bits of the counter.
For more information, refer to the RPCC() C-language built-in
documentation and the RPCC instruction in the Alpha Architecture Handbook.
Required Access or Privileges
None
Required Quota
None
$SAVE_VP_EXCEPTION (VAX Only)
On VAX systems, saves the pending exception state of the vector
processor.
Format
SYS$SAVE_VP_EXCEPTION excid
Argument
excid
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION. The
excid argument is the address of a longword containing
this ID.
Description
The Save Vector Processor Exception State service saves in memory any
pending vector exception state and clears the vector processor's
current exception state.
By default, when an AST or condition handler interrupts the execution
of a mainline routine, the operating system saves the mainline
routine's vector state, including its vector exception state. Any other
routine that executes synchronously with, or asynchronously to,
currently executing vectorized code and that performs vector operations
itself must preserve the preempted routine's vector exception state
across its own execution. It does so by using the $SAVE_VP_EXCEPTION
and $RESTORE_VP_EXCEPTION services. Used together, these services
ensure that vector exceptions occurring as a result of activity in the
original routine are serviced by existing condition handlers within
that routine.
In systems that do not have vector-present processors but do have the
VAX Vector Instruction Emulation facility (VVIEF) in use, VVIEF
emulates the functions of this service.
Required Access or Privileges
None
Required Quota
None
Related Services
$RELEASE_VP, $RESTORE_VP_EXCEPTION, $RESTORE_VP_STATE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. There were no pending vector
exceptions. The service also returns this status when executed in a
system that does not have vector-present processors and that does not
have the VAX Vector Instruction Emulation facility (VVIEF) loaded.
|
|
SS$_WASSET
|
The service completed successfully. Pending vector exception state has
been saved.
|
|
SS$_ACCVIO
|
The caller cannot write the exception ID longword.
|
|
SS$_INSFMEM
|
Insufficient system dynamic memory exists for completing the service.
|
$SCAN_INTRUSION
Scans the intrusion database for suspects or intruders during a login
attempt, audits login failures and updates records, or adds new records
to the intrusion database.
Format
SYS$SCAN_INTRUSION logfail_status ,failed_user ,job_type
,[source_terminal] ,[source_node] ,[source_user] ,[source_address]
,[failed_password] ,[parent_user] ,[parent_id] ,[flags]
C Prototype
int sys$scan_intrusion (unsigned int logfail_status, void *failed_user,
unsigned int job_type, void *source_terminal, void *source_node, void
*source_user, void *source_address, void *failed_password, void
*parent_user, unsigned int parent_id, unsigned int flags);
Arguments
logfail_status
| OpenVMS usage: |
status code |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Reason why the user's login attempt failed. The
logfail_status argument is a longword containing the
login failure status code.
The logfail_status argument can contain any valid
message code. For example, the value of the
logfail_status argument is SS$_NOSUCHUSER if the user
name the user entered does not exist on the system.
If the logfail_status argument contains a failure
status, the service performs a suspect scan. Here, the service searches
the intrusion database for intruder suspects as well as intruders. If
the value of the logfail_status argument is a
successful message, such as SS$_NORMAL, the service scans the database
only for intruders. For more information about how the database works,
refer to the HP OpenVMS Guide to System Security.
failed_user
| OpenVMS usage: |
char_string or item_list_3 |
| type: |
character-coded text string or longword
(unsigned) |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor or by
reference |
If the CIA$M_ITEMLIST flag is FALSE:
This argument is the user name associated with the unsuccessful login
attempt. The failed_user argument is the address of a
character-string descriptor pointing to the failed user name.
A failed user name consists of 1 to 32 alphanumeric characters.
If the CIA$M_ITEMLIST flag is TRUE:
The failed_user argument is the address of a 32-bit
item list. If the item list is used, one item, the CIA$_FAILED_USERNAME
item, must be present in the item list.
The following table lists the valid item descriptions for the
failed_user argument:
| Item |
Description |
|
CIA$_FAILED_USERNAME
|
Address of a buffer containing the failed user name.
|
|
CIA$_SCSNODE
|
Address of the 8-character null-padded SCS node name on which the
intrusion happened.
|
|
CIA$_USER_DATA
|
Address of a 256-byte buffer, available for passing third party
specified data.
|
job_type
| OpenVMS usage: |
job type |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Type of job that failed. The job_type argument is a
longword indicating the type of job that failed.
The $JPIDEF macro defines the following values for the
job_type argument:
- JPI$K_BATCH
- JPI$K_DETACHED
- JPI$K_DIALUP
- JPI$K_LOCAL
- JPI$K_NETWORK
- JPI$K_REMOTE
source_terminal
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Source terminal where the login attempt is occurring. The
source_terminal argument is the address of a
character-string descriptor pointing to the device name of the terminal
from which the login attempt originates.
A source terminal device name consists of 1 to 64 alphanumeric
characters, including underscores (_) and colons (:).
source_node
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the node from which the user's login attempt originates. The
source_node argument is the address of a
character-string descriptor pointing to the source node name string.
A source node name consists of 1 to 1024 characters. No specific
characters, format, or case is required for a source node name string.
source_user
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
User name associated with the login attempt. The
source_user argument is the address of a
character-string descriptor pointing to the source user name string.
A source user name consists of 1 to 32 alphanumeric characters,
including dollar signs ($) and underscores (_).
source_addr
| OpenVMS usage: |
node address |
| type: |
descriptor |
| access: |
read only |
| mechanism: |
by reference |
Source DECnet for OpenVMS address from which the login attempt
originates. The source_addr argument is the address of
a descriptor containing the source node address.
failed_password
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Password the user entered for the login attempt. The
failed_password argument is the address of a
character-string descriptor pointing to the plaintext password the user
entered to log in.
A failed password is a password of 0 to 32 characters that did not
allow the user to log in to the system. This argument is not stored in
the intrusion database and is only used for auditing during break-in
attempts.
parent_user
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Parent process name of the failed login. The
parent_user argument is the address of a
character-string descriptor pointing to the parent process name of the
failed login process.
|
