fchaudit (BPX1FCA, BPX4FCA) — Change audit flags for a file by descriptor

Function

The fchaudit callable service changes the types of access to a file to be audited for the security product. You identify the file by its file descriptor.

For the corresponding service using a pathname, see chaudit (BPX1CHA, BPX4CHA) — Change audit flags for a file by path.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1FCA):	31-bit
AMODE (BPX4FCA):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1FCA,(File_descriptor,
              Audit_flags,
              Option_code,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4FCA with the same parameters.

Parameters

File_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword containing the file descriptor of the file to be changed.

Audit_flags

Supplied parameter

Type:: Structure
Length:: Fullword

The name of a fullword indicating the access to be audited. This field is mapped by the BPXYAUDT macro; see BPXYAUDT — Map flag values for chaudit and fchaudit. Values for this field include any combination of the following:

Value	Description
AUDTREADFAIL	Audit failing read requests.
AUDTREADSUCCESS	Audit successful read requests.
AUDTWRITEFAIL	Audit failing write requests.
AUDTWRITESUCCESS	Audit successful write requests.
AUDTEXECFAIL	Audit failing execute or search requests.
AUDTEXECSUCCESS	Audit successful execute or search requests.

Option_code

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword field that indicates whether you are changing the auditing for flags of the user or of the auditor. When this field has the value:

0: User audit flags are changed.
1: Auditor audit flags are changed.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword where the fchaudit service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

Return_code	Explanation
EBADF	The File_descriptor parameter is not a valid file descriptor.
EINVAL	The Option_code parameter is incorrect, or File_descriptor refers to an unnamed pipe and fchaudit is not allowed on such a file.
EPERM	The effective user ID of the calling process does not match the owner of the file, the calling process does not have appropriate privileges (see Authorization), or if Option_code indicated that the auditor audit flags were to be changed, then the user may not have had auditor authority.
EROFS	The specified file is on a read-only file system. The following reason code can accompany the return code: JRReadOnlyFS.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword where the fchaudit service stores the reason code. The fchaudit service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

If Option_code indicates that the auditor audit flags are to be changed, the user must have auditor authority for the request to be successful. The user with auditor authority can set the auditor options for any file, even those for which they do not have path access or authority to use for other purposes.
You can get auditor authority by issuing the TSO/E command ALTUSER Auditor.
If Option_code indicates that the user audit flags are to be changed, the user must have appropriate privileges (see Authorization), or be the owner of the file.

fchaudit (BPX1FCA, BPX4FCA) — Change audit flags for a file by descriptor

Function

Requirements

Format

Parameters

Usage notes

Related services

Characteristics and restrictions

Examples