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

CALL BPX1CHA,(Pathname_length,
              Pathname,
              Audit_flags,
              Option_code,
              Return_value,
              Return_code,
              Reason_code)

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 nme 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:
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 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

  1. 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.

  2. 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.

Parent topic: Callable services descriptions