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 path name, 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 a list of reason codes, see Reason codes in 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.
Related services
Characteristics and restrictions
There are no restrictions on the use of the fchaudit service.