chaudit (BPX1CHA, BPX4CHA) — Change audit flags for a file by path
Function
The chaudit service changes the types of access to a file to be audited for the security product. The chaudit service identifies the file by its path name.
For the corresponding service using a file descriptor, see fchaudit (BPX1FCA, BPX4FCA) — Change audit flags for a file by descriptor.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1CHA): | 31-bit |
AMODE (BPX4CHA): | 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
|
AMODE 64 callers use BPX4CHA with the same parameters.
Parameters
- Pathname_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length of the path name of the file.
- Pathname
- Supplied parameter
- Type:
- Character string
- Character set:
- No restriction
- Length:
- Specified by the Pathname_length parameter
The name of a field that contains the path name of the file for which auditing is to be changed.
Path names can begin with or without a slash:- A path name that begins with a slash is an absolute pathname. The slash refers to the root directory, and the search for the file starts at the root directory.
- A path name that does not begin with a slash is a relative pathname. The search for the file starts at the working directory.
- Audit_flags
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that indicates the access to be audited. This field is mapped by the BPXYAUDT macro; see BPXYAUDT — Map flag values for chaudit and fchaudit. Valid values for this field include any combination of the following:- AUDTREADFAIL
- Audit requests that are failing.
- AUDTREADSUCCESS
- Audit successful read requests.
- AUDTWRITEFAIL
- Audit write requests that are failing.
- AUDTWRITESUCCESS
- Audit successful write requests.
- AUDTEXECFAIL
- Audit execute or search requests that are failing.
- AUDTEXECSUCCESS
- Audut 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 the user or for the security auditor. When this field has the value:- 0, the user's auditing is being changed.
- 1, the security auditor's auditing is being changed. A superuser who is not the auditor cannot change the auditor's authority.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the chaudit service returns 0 if the request is successful, or -1 if it is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the chaudit service stores the return code. The chaudit service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a list of possible return code values. The chaudit service can return one of the following values in the Return_code parameter:Return_code Explanation EACCES The calling process does not have search permission for some component of the Pathname prefix. EINVAL The Option_code parameter is incorrect. The following reason code can accompany the return code: JRBadAuditOption. ELOOP A loop exists in symbolic links that were encountered during resolution of the Pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of Pathname. ENAMETOOLONG Pathname is longer than 1023 characters, or some component of the path name is longer than 255 characters. Name truncation is not supported. ENOENT No file named Pathname was found, or no path name was specified. The following reason code can accompany the return code: JRFileNotThere. ENOTDIR A component of the Pathname prefix is not a directory. EPERM The effective UID of the calling process does not match the file's owner UID; the calling process does not have appropriate privileges (see Authorization); or if Option_code indicated that the auditor audit flags were to be changed, the user does not have auditor authority. EROFS The file exists 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 in which the chaudit service stores the reason code. The chaudit service returns a 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 entering 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 chaudit service.
Examples
For an example using this callable service, see BPX1CHA (chaudit) example.