Searches for and returns information about records in the
intrusion database matching the caller's specifications.
Format
SYS$SHOW_INTRUSION user_criteria ,intruder ,intruder_len
,breakin_block ,[flags] ,[context]
C Prototype
int sys$show_intrusion (void *user_criteria, void *intruder,
unsigned short int *intruder_len, void
*breakin_block, unsigned int flags,
unsigned int *context);
1 – Arguments
user_criteria
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:
The user_criteria argument is the description of intruder
or suspect. The user_criteria argument is the address of a
character-string descriptor pointing to a buffer containing the
user criteria to match an intrusion record's user specification
in the intrusion database.
The user_criteria argument is a character string of between 1 and
1058 bytes containing characters to match the user specification
on records in the intrusion database.
A user specification is any combination of the suspect's or
intruder's source node name, source user name, source DECnet
for OpenVMS address, local failed user name, local terminal,
or the string UNKNOWN. The user specification for an intrusion
record is based on the input to the $SCAN_INTRUSION service and
the settings of the LGI system parameter. For more information,
see the VSI OpenVMS Guide to System Security.
Wildcards are allowed for the user_criteria argument.
For more information about using wildcards to scan the intrusion
database, see the $SHOW_INTRUSION Description section in the VSI
OpenVMS System Services Reference Manual.
If the CIA$M_ITEMLIST flag is TRUE:
The user_criteria argument is now the address of an 32-bit item
list. If the item list is used, one item, the CIA$_USER_CRITERIAL
item, must be present in the item list.
The following table lists the valid item descriptions for the
user_criteria argument:
Item Description
CIA$_OUTPUT_LIST Address of an 8192-byte buffer into which the
service writes the associated node information
for the returned intrusion record.
CIA$_SCSNODE_LIST Address of a list of 8-character null-padded
SCS nodenames for which the caller wants to
see intrusion information about.
CIA$_USER_ Address of a buffer, 1-1058 bytes long,
CRITERIAL containing the intruder or suspect.
If a CIA$_SCSNODE_LIST item is provided, an intrusion record will
only be returned if it originated on one of the nodes specified.
If a CIA$_SCSNODE_LIST item is not provided, records from all
nodes will be candidates for display. Multiple CIA$_SCSNODE_LIST
items are permitted in the item list.
If a CIA$_OUTPUT_LIST item is provided, the item is filled with
node-count records on return. The returned intrusion record will
have a breakin block with a valid attempt-count field. The node-
count records will have the name and attempt-count for each node
represented.
intruder
OpenVMS usage:char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed-length string descriptor
User specification of the matched intruder or suspect record in
the intrusion database. The intruder argument is the address of
a character-string descriptor pointing to a buffer to receive
the user specification of the matched record in the intrusion
database.
The intruder argument is a 1058-byte string that will receive
the user specification of a record in the intrusion database
that matches the specifications in the user_criteria and flags
arguments.
intruder_len
OpenVMS usage:string length
type: longword (unsigned)
access: write only
mechanism: by reference
Length of returned string in the intrusion buffer. The intruder_
len argument is the address of a longword to receive the length
of the returned intrusion buffer.
The possible range of the intruder_len argument is 0 to 1058
bytes. If the longword specified by the argument contains a 0
after the call to the service, either the service did not find a
record that matched the user criteria in the intrusion database,
or there are no more matching items in the intrusion database.
breakin_block
OpenVMS usage:record
type: block of 2 longwords (unsigned) and
1 quadword (unsigned)
access: write only
mechanism: by reference
Block to receive various information in the intrusion database
about a record matching the user criteria.
Refer to the VSI OpenVMS System Services Reference Manual to view
the breakin_block argument diagram and descriptor fields table.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Type of records in the intrusion database about which information
is to be returned. The flags argument is a longword bit mask
wherein each bit corresponds to an option.
Each option has a symbolic name. The $CIADEF macro defines the
following valid names:
Symbolic Name Description
CIA$M_ALL All records will be shown. If the flags
argument is omitted, this value is assumed.
CIA$M_INTRUDERS Only intruder records matching the criteria
specified by the user_criteria argument will
be returned. The value of the flag field in
the break-in block will always be 1.
CIA$M_ITEMLIST If FALSE, the user_criteria argument is a
character string. If TRUE, this argument is a
32-bit item list.
CIA$M_SUSPECTS Only suspect records matching the criteria
specified by the user_criteria argument will
be returned. The value of the flag field in
the break-in block will always be 0.
Each of these options is mutually exclusive.
context
OpenVMS usage:context
type: longword (unsigned)
access: write only
mechanism: by reference
Context information to keep between related calls to the $SHOW_
INTRUSION service. The context argument is the address of a
longword that receives a context from the service.
The initial value contained in the unsigned longword pointed to
by the context argument must be 0. The contents of the unsigned
longword must not be changed after the service has set its value.
If the contents of the context argument are changed between calls
to the service, SS$_BADCONTEXT will be returned.
Contexts become invalid after one-half hour of non-use. This
means that if you call the $SHOW_INTRUSION service with a
wildcard in the user_criteria argument and do not call the
service to get the next matching record within one-half hour,
the context becomes invalid. If the context has become invalid,
you must restart your search of the intrusion database from the
beginning by resetting the context to 0.