chattr (BPX1CHR, BPX4CHR) — Change the attributes of a file or directory

Function

The chattr service modifies the attributes that are associated with a file. It can be used to change the mode, owner, access time, modification time, change time, reference time, audit flags, general attribute flags, file format and size, and file tag. It can also be used to set the initial security label for a file or directory. Identify the file by its path name.

For the corresponding service using a file descriptor, see fchattr (BPX1FCR, BPX4FCR) — Change the attributes of a file or directory by descriptor.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1CHR):	31-bit
AMODE (BPX4CHR):	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

The syntax format is as follows:

CALL BPX1CHR,(Pathname_length,
              Pathname,
              Attributes_length,
              Attributes,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4CHR 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 whose attributes you want to change.

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. The length of this field is specified in Pathname_length.

Attributes_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the area containing the attributes that you want to change.

Attributes

Supplied parameter

Type:: Structure
Length:: Specified by the Attributes_length parameter

The name of the area that contains the attributes you want to change. The area is mapped by BPXYATT. For information about the content of this area, see BPXYATT — Map file attributes for chattr and fchattr.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the chattr 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 chattr service stores the return code. The chattr service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The chattr service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The calling process did not have appropriate permissions. Possible reasons include: The calling process was attempting to set access time or modification time to current time, and the effective UID of the calling process does not match the owner of the file; the process does not have write permission for the file; or the process does not have appropriate privileges (see Authorization). The calling process was attempting to truncate the file, and it does not have write permission for the file.
EBUSY	The file is open by a remote NFS client with a share reservation that conflicts with the requested operation.
EFBIG	The calling process was attempting to change the size of a file, but the specified length is greater than the maximum file size limit for the process. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRWriteBeyondLimit.
EINVAL	The length of the Attributes parameter is too small, or the Attributes structure containing the requested changes is not valid. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JrInvalidAtt, JrNegativeValueInvalid, JrTrNotRegFile, JrTrNegOffset, JrFileNotEmpty, and JrInvalidFileTag.
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.
EMVSERR	An MVS™ environmental error has been detected. The following reason code can accompany the return code: JrSeclabelClassInactive.
ENAMETOOLONG	Pathname is longer than 1023 characters, or a component of the path name is longer than 255 characters. (File 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.
ENOSYS	The function is not supported for the specified file. The following reason code can accompany the return code: JrNotSupportedForFileType.
ENOTDIR	Some component of Pathname is not a directory.
EPERM	The operation is not permitted for one of the following reasons: The calling process was attempting to change the mode or the file format, but the effective UID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges (see Authorization). The calling process was attempting to change the owner, but it does not have appropriate privileges. The calling process was attempting to change the general attribute bits, but it does not have write permission for the file. The calling process was attempting to set a time value (not current time), but the effective user ID does not match the owner of the file, and it does not have appropriate privileges. The calling process was attempting to set the change time or reference time to current time, but it does not have write permission for the file. The calling process was attempting to change auditing flags, but the effective UID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges. The calling process was attempting to change the security auditor's auditing flags, but the user does not have auditor authority. Attributes indicate that the security label is to be set, and one or more of the following conditions apply: The calling process does not have RACF® SPECIAL authorization and appropriate privileges. There is already a security label that is associated with the file.
EROFS	Pathname specifies a file that is on a read-only file system. Consult Reason_code to determine the exact reason that the error occurred. 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 chattr service stores the reason code. The chattr service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

Table 1. Attribute fields that can be modified by chattr
Set flags	Attribute fields input	Description
ATTMODECHG	ATTMODE	Set the mode according to the value in ATTMODE. See chmod (BPX1CHM, BPX4CHM) — Change the mode of a file or directory.
ATTOWNERCHG	ATTUID ATTGID	Set the owner user identifier (UID) and group identifier (GID) to the values specified in ATTUID and ATTGID. See chown (BPX1CHO, BPX4CHO) — Change the owner or group of a file or directory.
ATTSETGEN	ATTGENVALUE ATTGENMASK	Only the bits corresponding to the bits set ON in the ATTGENMASK are set to the value (ON or OFF) in ATTGENVALUE. Other bits are unchanged.
ATTTRUNC	ATTSIZE	Change the file size to ATTSIZE bytes. See ftruncate (BPX1FTR, BPX4FTR) — Change the size of a file.
ATTATIMECHG	ATTATIME	If ATTLP64TIMES is not set, set the access time of the file to the value specified in ATTATIME. If ATTLP64TIMES is set, set the access time of the file to the value specified in ATTATIME64, which is a doubleword field.
ATTATIMETOD	None	Set the access time of the file to the current time.
ATTMTIMECHG	ATTMTIME	If ATTLP64TIMES is not set, set the modification time of the file to the value specified in ATTMTIME. If ATTLP64TIMES is set, set the modification time of the file to the value specified in ATTMTIME64, which is a doubleword field.
ATTMTIMETOD	None	Set the modification time of the file to the current time.
ATTMAAUDIT	ATTAUDITORAUDIT	Set the security auditor's auditing flags to the value specified in ATTAUDITORAUDIT. See chaudit (BPX1CHA, BPX4CHA) — Change audit flags for a file by path.
ATTMUAUDIT	ATTUSERAUDIT	Set the User's auditing flags to the value specified in ATTUSERAUDIT. See chaudit (BPX1CHA, BPX4CHA) — Change audit flags for a file by path.
ATTCTIMECHG	ATTCTIME	If ATTLP64TIMES is not set, set the change time of the file to the value specified in ATTCTIME. If ATTLP64TIMES is set, set the change time of the file to the value specified in ATTCTIME64, which is a doubleword field.
ATTCTIMETOD	None	Set the change time of the file to the current time.
ATTREFTIMECHG	ATTREFTIME	If ATTLP64TIMES is not set, set the reference time of the file to the value specified in ATTREFTIME. If ATTLP64TIMES is set, set the reference time of the file to the value specified in ATTREFTIME64, which is a doubleword field.
ATTREFTIMETOD	None	Set the reference time of the file to the current time.
ATTFILEFMTCHG	ATTFILEFMT	Set the File Format of the file to the value specified in ATTFILEFMT.
ATTCHARSETIDCHG	ATTFILETAG	Set the file tag. See BPXYSTAT (BPXYSTAT — Map the response structure for stat) for file tag mapping.
ATTSECLABELCHG	ATTSECLABEL	Set the initial security label for a file or directory.

Flags in the Attributes parameter are set to indicate which attributes are to be updated. To set an attribute, turn the corresponding Set Flag on, and set the corresponding Attributes Field according to Table 1. Multiple attributes may be changed at the same time.
The Set Flag field should be cleared before any bits are turned on. It is considered an error if any of the reserved bits in the flag field are turned on.
Some of the attributes that are changed by the chattr service can also be changed by other services. See the related service (listed in Table 1) for a detailed description.
Changing mode (ATTMODECHG = ON):
- The file mode field in Attributes is mapped by the BPXYMODE macro (see BPXYMODE — Map the mode constants of the file services). For information on the values for file type, see BPXYFTYP — File type definitions.
- File descriptors that are open when the chattr service is called retain the access permission they had when the file was opened.
- The effective UID of the calling process must match the file's owner UID, or the caller must have appropriate privileges (see Authorization).
- Setting the set-group-ID-on-execution permission (in mode) means that when this file is run through the exec, attach_exec, or spawn service, the effective GID of the caller is set to the file's owner GID, so that the caller seems to be running under the GID of the file, rather than that of the actual invoker.
  The set-group-ID-on-execution permission is set to zero if both of the following are true:
  - The caller does not have appropriate privileges.
  - The GID of the file's owner does not match the effective GID, or one of the supplementary GIDs, of the caller.
- Setting the set-user-ID-on-execution permission (in mode) means that when this file is run, the process's effective UID is set to the file's owner UID, so that the process seems to be running under the UID of the file's owner, rather than that of the actual invoker.
Changing owner (ATTOWNERCHG = ON):
- To change the owner UID of a file, the caller must have appropriate privileges.
- To change the owner GID of a file, the caller must have appropriate privileges, or meet all of these conditions:
  - The effective UID of the caller matches the file's owner UID.
  - The Owner_UID value that is specified in the change request matches the file's owner UID.
  - The Group_ID value that is specified in the change request is the effective GID, or one of the supplementary GIDs, of the caller.
- When the owner is changed, the set-user-ID-on-execution and set-group-ID-on-execution permissions of the file mode are automatically turned off.
- When the owner is changed, both UID and GID must be specified as they are to be set, or set to -1 if the value is to remain unchanged. If only one of these values is to be changed, the other can be set to its present value or to -1 to remain unchanged.
Changing General Attribute bits (ATTSETGEN = ON):
- For General Attribute bits to be changed, the calling process must have write permission for the file.
Changing the file size (ATTTRUNC = ON):
- The resizing of a file to ATTSIZE bytes changes the file size to ATTSIZE, beginning from the first byte of the file. If the file was originally larger than ATTSIZE bytes, the data from ATTSIZE to the original end of file is removed. If the file was originally shorter than ATTSIZE, bytes between the old and new lengths are read as zeros.
  Full blocks are returned to the file system so that they can be used again.
  
  The file offset is not changed.
- When a file size is changed successfully, it clears the set-user-ID, the set-group-ID, and the save-text (sticky bit) attributes of the file, unless the caller has appropriate privileges.
- The resizing of a file to ATTSIZE bytes, where ATTSIZE is greater than the soft file size limit for the process, fails with EFBIG, and the SIGXFSZ signal is generated for the process.
- A file's size cannot be changed if it is open by a remote NFS client with a share reservation that prevents the file from being opened for writing. Refer to open (BPX1OPN, BPX4OPN) — Open a file for details about the NFS share reservations.
Changing times:
- All time fields in Attributes are in POSIX format.
- For the access time or the modification time to be set explicitly (ATTATIMECHG = ON or ATTMTIMECHG = ON), the effective ID must match the file's owner, or the process must have appropriate privileges.
- For the access time or modification time to be set to the current time (ATTATIMETOD = ON or ATTMTIMETOD = ON), the effective ID must match the file's owner, the calling process must have write permission for the file, or the process must have appropriate privileges.
- For the change time or the reference time to be set explicitly (ATTCTIMECHG = ON or ATTREFTIMECHG = ON), the effective ID must match the file's owner, or the process must have appropriate privileges.
- For the change time or reference time to be set to the current time (ATTCTIMETOD = ON or ATTREFTIMETOD = ON), the calling process must have write permission for the file.
- For any time field (atime, mtime, ctime, reftime), if both current time and specific time are requested (for example, ATTCTIMETOD = ON and ATTCTIMECHG = ON), the current time is set.
- When any attribute field is changed successfully, the file's change time is also updated.
Changing auditor audit flags (ATTMAAUDIT = ON):
- For auditor audit flags to be changed, the user must have auditor authority. Users 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 establish auditor authority by issuing the TSO/E command ALTUSER Auditor.
Changing user audit flags (ATTMUAUDIT = ON):
- For the user audit flags to be changed, the user must have appropriate privileges (see Authorization) or be the owner of the file.
Changing the file format (ATTFILEFMTCHG = ON):
- The effective UID of the calling process must match the file's owner UID, or the caller must have appropriate privileges.
- The attribute that is specified in ATTFILEFMT is the same attribute that is set by the FILEDATA=TEXT parameter on a DD statement.
Changing the file tag (ATTCHARSETIDCHG=ON):
- A file tag can be set for regular, FIFO, and character special files. If the DeferTag bit is on in the file tag, the file must be empty.
- The tagging of /dev/null, /dev/random, /dev/urandom, and /dev/zero is ignored.
Changing the security label (ATTSECLABELCHG=ON):
- For the security label to be changed, the user must have RACF SPECIAL authorization and appropriate privileges (see Authorization), and no security label must currently exist on the file. Only an initial security label can be set. An existing security label cannot be changed. The function will successfully set the security label if the RACF SECLABEL class is active. If the SECLABEL class is not active, a return code of EMVSERR will be returned.

Related services

Characteristics and restrictions

The ATTEXTLINK flag in the ATTGENVALUE field of BPXYATT cannot be modified with BPX1CHR (BPX4CHR).
The general attribute fields (set by ATTSETGEN, ATTGENMASK, and ATTGENVALUE fields) are not intended as a general-use programming interface to BPX1CHR (BPX4CHR).
The security label (ATTSECLABELCHG) flag requires RACF SPECIAL authorization and appropriate privileges (see Authorization). It cannot be used to change an existing security label; it can only be used to set an initial security label on a file.

Examples

For an example that uses this callable service, see BPX1CHR (chattr) example.