Document revision date: 19 July 1999

The flag field contains information applicable to all types of ACEs. The following symbols are bit offsets to ACE information that is independent of ACE type.

Bit Position	Meaning When Set
ACE$V_HIDDEN	This ACE is application dependent. You cannot use the DCL ACL commands and the ACL editor to change the setting; the DCL command DIRECTORY/ACL does not display it.
ACE$V_NOPROPAGATE	This ACE is not propagated among versions of the same file.
ACE$V_PROTECTED	This ACE is not deleted if the entire ACL is deleted; instead you must delete this ACE explicitly.

The system interprets the bits within the access mask as shown in the following table. The following symbol values are offsets to bits within the mask indicating the access mode granted in the system, owner, group, and world fields.

Bit Position	Meaning When Set
ACE$V_READ	Read access is granted.
ACE$V_WRITE	Write access is granted.
ACE$V_EXECUTE	Execute access is granted.
ACE$V_DELETE	Delete access is granted.

You can also obtain the symbol values as masks with the appropriate bit set by using the prefix ACE$M rather than ACE$V.

Identifier ACE

The Identifier ACE controls access to an object based on identifiers. Its format is as follows.

The following table describes the ACE fields and lists the symbol name for each.

Field	Symbol Name	Description
Length	ACE$B_SIZE	Byte containing the length in bytes of the ACE buffer.
Type	ACE$B_TYPE	Byte containing the type value ACE$C_KEYID.
Flags	ACE$W_FLAGS	Word containing Identifier ACE information and ACE type-independent information.
Access	ACE$L_ACCESS	Longword containing a mask indicating the access mode granted to the specified identifiers.
Reserved	ACE$V_RESERVED	Longwords containing application-specific information. The number of reserved longwords is specified in the flags field.
Identifier	ACE$L_KEY	Longwords containing identifiers. The number of longwords is implied by ACE$B_SIZE. If an accessor holds all of the listed identifiers, the ACE is said to match the accessor, and the access specified in ACE$L_ACCESS is granted.

The flags field contains information specific to Identifier ACEs and information applicable to all types of ACEs. The following symbol is a bit offset to Identifier ACE information.

Bit	Meaning When Set
ACE$V_RESERVED	Four-bit field containing the number of longwords to reserve for application-dependent data. The number must be between 0 and 15. The reserved longwords, if any, immediately precede the identifiers.

The following symbols are bit offsets to ACE information that is independent of ACE type.

Bit	Meaning When Set
ACE$V_DEFAULT	This ACE is added to the ACL of any file created in the directory whose ACL contains this ACE. This bit is applicable only for an ACE in a directory file's ACL.
ACE$V_HIDDEN	This bit is application dependent. You cannot use the DCL ACL commands and the ACL editor to change the setting; the DCL command DIRECTORY/ACL does not display it.
ACE$V_NOPROPAGATE	This ACE is not propagated among versions of the same file.
ACE$V_PROTECTED	This ACE is not deleted if the entire ACL is deleted; instead you must delete this ACE explicitly.

The following symbol values are offsets to bits within the mask indicating the access mode granted in the system, owner, group, and world fields.

Bit Position	Meaning When Set
ACE$V_READ	Read access is granted.
ACE$V_WRITE	Write access is granted.
ACE$V_EXECUTE	Execute access is granted.
ACE$V_DELETE	Delete access is granted.
ACE$V_CONTROL	Modification of the access field is granted.

You can also obtain the symbol values as masks with the appropriate bit set by using the prefix ACE$M rather than ACE$V.

Subsystem ACE

The Subsystem ACE maintains protected subsystems. Its format is as follows.

The following table describes the ACE fields and lists the symbol name for each.

Field	Symbol Name	Description
Length	ACE$B_SIZE	Byte containing the length in bytes of the ACE buffer.
Type	ACE$B_TYPE	Byte containing the type value ACE$C_SUBSYSTEM_IDS.
Flags	ACE$W_FLAGS	Word containing Subsystem ACE information and ACE type-independent information.
Spare	ACE$L_SPARE1	Longword that is reserved for future use and must be 0.
Identifier/Attributes	ACE$Q_IMAGE_IDS	Longword identifier value and its associated longword attributes.

A Subsystem ACE can contain multiple identifier/attribute pairs. In this case, the Subsystem ACE is an array of identifiers and attributes starting at ACE$Q_IMAGE_IDS. Beginning at this offset, KGB$L_IDENTIFIER and KGB$L_ATTRIBUTES are used to address each of the separate longwords.

The number of identifier/attribute pairs is computed by subtracting ACE$C_LENGTH from ACE$W_SIZE and dividing by KGB$S_IDENTIFIER.

The following symbols are bit offsets to ACE information that is independent of ACE type.

Bit	Meaning When Set
ACE$V_NOPROPAGATE	This ACE is not propagated among versions of the same file.
ACE$V_PROTECTED	This ACE is not deleted if the entire ACL is deleted; instead you must delete this ACE explicitly.

The following symbol values are offsets to bits within the mask indicating the access mode granted in the system, owner, group, and world fields.

Bit Position	Meaning When Set
ACE$V_READ	Read access is granted.
ACE$V_WRITE	Write access is granted.
ACE$V_EXECUTE	Execute access is granted.
ACE$V_DELETE	Delete access is granted.
ACE$V_CONTROL	Modification of the access field is granted.

You can also obtain the symbol values as masks with the appropriate bit set by using the prefix ACE$M rather than ACE$V.

Required Access or Privileges

None

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $CREATE_USER_PROFILE, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_RESOURCE_DOMAIN, $SET_SECURITY

Condition Values Returned

SS$_BUFFEROVF	The service completed successfully. The output string has overflowed the buffer and has been truncated.
SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The ACL entry or its descriptor cannot be read by the caller, or the string descriptor cannot be read by the caller, or the length word or the string buffer cannot be written by the caller.

Converts a security auditing event message from binary format to ASCII text.

Format

SYS$FORMAT_AUDIT fmttyp ,audmsg ,[outlen] ,outbuf ,[width] ,[trmdsc] ,[routin] ,[fmtflg]

C Prototype

int sys$format_audit (unsigned int fmttyp, void *audmsg, unsigned short int *outlen, void *outbuf, unsigned short int *width, void *trmdsc, int (*routin)(__unknown_params), unsigned int fmtflg);

Arguments

fmttyp

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

Format for the message. The fmttyp argument is a value indicating whether the security audit message should be in brief format, which is one line of information, or full format. The default is full format. See the OpenVMS System Manager's Manual for examples of formatted output.

The following table defines the brief and full formats.

Value	Meaning
NSA$C_FORMAT_STYLE_BRIEF	Use a brief format for the message.
NSA$C_FORMAT_STYLE_FULL	Use a full format for the message.

audmsg

OpenVMS usage:	char_string
type:	byte stream (unsigned)
access:	read only
mechanism:	by reference

Security auditing message to format. The audmsg argument is the address of a buffer containing the message that requires formatting.

outlen

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Length of the formatted security audit message. The outlen argument is the address of the word receiving the final length of the ASCII message.

outbuf

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

Buffer holding the formatted message. The outbuf argument is the address of a descriptor pointing to the buffer receiving the message.

width

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	read only
mechanism:	by reference

Maximum width of the formatted message. The width argument is the address of a word containing the line width value. The default is 80 columns.

The width argument does not work consistently. In most cases, if you specify both the width argument and the full format style (NSA$C_FORMAT_STYLE_FULL), $FORMAT_AUDIT ignores the width argument. The minimum width is 80 columns; lower values do not limit the width to less than 80. If you specify a width greater than 80 columns, most lines are not joined to use the full width.

In most cases, you should avoid using the width argument.

trmdsc

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

Line termination characters used in a full format message. The trmdsc argument is the address of a descriptor pointing to the line termination characters to insert within a line segment whenever the width is reached.

routin

OpenVMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by reference

Routine that writes a formatted line to the output buffer. The routin argument is the address of a routine called each time a line segment is formatted. The argument passed to the routine is the address of a character string descriptor for the line segment.

When an application wants event messages in the brief format, $FORMAT_AUDIT calls the routine twice to format the first event message. The first time it is called, the routine passes a string containing the column titles for the message. The second and subsequent calls to the routine pass the formatted event message. By using this routine argument, a caller can gain control at various points in the processing of an audit event message.

fmtflg

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

Determines the formatting of certain kinds of audit messages. The fmtflg argument is a mask specifying whether sensitive information should be displayed or column titles built for messages in brief format. For example, the operating system uses bit 0 to suppress plain-text passwords from security alarm messages. The following table describes the significant bits.

Bit	Value	Description
0	1	Do not format sensitive information.
	0	Format sensitive information.
1	1	Build a column title for messages in brief format. (You must specify a fmttyp of brief and a routin argument.)
	0	Do not build column titles.

Description

The Format Audit service converts a security auditing event message from binary format to ASCII text and can filter sensitive information. $FORMAT_AUDIT allows the caller to format a message in a multiple-line format or a single-line format and tailor the information for a display device of a specific width.

$FORMAT_AUDIT is intended for utilities that need to format the security auditing event messages received from the audit server listener mailbox or the system security audit log file.

Required Access or Privileges

None

Required Quota

$FORMAT_AUDIT can cause a process to exceed its page-file quota (PGFLQUOTA) if it has to format a long auditing event message. The caller of $FORMAT_AUDIT can also receive quota violations from services that $FORMAT_AUDIT uses, such as $IDTOASC, $FAO, and $GETMSG.

Related Services

$AUDIT_EVENT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_MSGNOTFND	The service completed successfully; however, the message code cannot be found and a default message has been returned.
SS$_ACCVIO	The item list cannot be read by the caller, or the buffer length or buffer cannot be written by the caller.
SS$_BADPARAM	The item list contains an invalid identifier.
SS$_BUFFEROVF	The service completed successfully; however, the formatted output string overflowed the output buffer and has been truncated.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVCHAN	The format of the specified identifier is not valid. This condition value returned is not directly returned by $FORMAT_AUDIT. It is indirectly returned when $FORMAT_AUDIT in turn calls another service, such as an identifier translation or binary time translation service.
SS$_IVIDENT	The format of the specified identifier is invalid.
SS$_NOSUCHID	The specified identifier name does not exist in the rights database. This condition value returned is not directly returned by $FORMAT_AUDIT. It is indirectly returned when $FORMAT_AUDIT in turn calls another service, such as an identifier translation or binary time translation service.

On Alpha systems, releases a user capability, indicating to other processes that the resource is now available.

This service accepts 64-bit addresses.

Format

SYS$FREE_USER_CAPABILITY cap_num [,prev_num] [,flags]

C Prototype

int sys$free_user_capability (int *cap_num, struct _generic_64 *prev_mask, struct _generic_64 *flags);

Arguments

cap_num

OpenVMS usage:	longword
type:	longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Capability number to be released by the calling Kernel thread. This number can range from 1 to 16. The cap_num argument is the 32- or 64-bit address of the longword containing the user capability number.

prev_mask

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The previous user capability reservation mask before execution of this service call. The prev_mask argument is the 32- or 64-bit address of a quadword into which the service writes a quadword bit mask specifying the previously reserved user capabilities.

flags

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Options selected for the user capability reservation. The flags argument is a quadword bit vector wherein a bit corresponds to an option.

Each option (bit) has a symbolic name, which the $CAPDEF macro defines. The flags argument is constructed by performing a logical OR operation using the symbolic names of each desired option.

At this time, all bits are reserved to Compaq and must be 0.

Description

The Release a Reserved User Capability service releases a user capability back to the global pool, making it available for subsequent calls to $GET_USER_CAPABILITY. The state of all user capabilities in the system are kept in SCH$GQ_RESERVED_USER_CAPS; this service clears the bit position in that cell reflecting the capability number specified in cap_num.

This service can also return the state of the global reservation bit mask prior to a release operation.

Required Privileges

The caller must have both ALTPRI and WORLD privileges to call $FREE_USER_CAPABILITY to release a user capability. No privileges are required if $FREE_USER_CAPABILITY is called only to retrieve the current user capability reservation mask.

Required Quota

None

Related Services

$GET_USER_CAPABILITY, $CPU_CAPABILITIES, $PROCESS_CAPABILITIES

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_INSFARG	Fewer than the required number of arguments were specified, or no operation was specified.
SS$_NOPRIV	Insufficient privilege for the attempted operation.
SS$_TOO_MANY_ARGS	Too many arguments were presented to the system service.
SS$_WASCLR	The requested user capability was already released.

	privacy and legal statement
4527PRO_040.HTML