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 that uses 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 that 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 that you want to change. The area is mapped by BPXYATT. For more information about the content of this area, see BPXYATT — Map file attributes for chattr and fchattr.

For extended attributes, the area is mapped by the attx structure in the same BPXYATT mapping. Storage for the attribute value must be contiguous with the attx structure and the attributes_length argument is the length of the attx structure plus the length of the attribute value.

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. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes 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, but 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.
EEXIST A request to create an extended attribute was specified, but the attribute is already set. The following reason code can accompany the return code: JrAttxExists.
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 that the error occurred. The following reason code can accompany the return code: JRWriteBeyondLimit.
EINVAL

The extended attribute operation is invalid due to the values that are being passed. The input length for the ATTX parameter might be insufficient or the subcommand AttxSubCmd is invalid. The following reason codes can accompany the return code: JRInvMinArgLenAttx, JRInvArgLenAttx, JRInvAttxCmd.
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 was 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.)
ENOATTR For the replace or remove function, the specified extended attribute cannot be set. ENOATTR is also set if the passed in attribute name, AttxName, is empty. The following reason codes can accompany the return code: JrAttxName and JrAttxUnavail.
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.
ENOTSUP The request against an extended attribute is not supported. The following reason codes can accompany the return code: JRInvAttxFTyp, JrSetAttxTrustClas, JRAttxNoSup, and JRSetAttxNameSpc.
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. However, the effective UID of the calling process does not match the owner of the file and the calling process does not have appropriate privileges. For more information, 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). However, 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. However, 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.
    • A security label is already associated with the file.
ERANGE The length of the extended attribute value to be set, AttxValLn, does not match the attribute size itself. For example, ERANGE can occur when a 4-byte attribute is being set to a 2-byte or 6-byte value. The following reason code can accompany the return code: JrInvAttxValLen.
EROFS Pathname specifies a file that is on a read-only file system. Consult the 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 the 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.

Changing extended attributes

To add, remove, or modify extended attributes, use the extended attributes control block ATTX in place of the standard ATT control block. For mapping to ATTX, see BPXYATT — Map file attributes for chattr and fchattr. Rather than turning on flags within the control block like ATT, ATTX supports an attribute name field, AttxName, to specify which attribute to take action against. The ATTX mapping is variable length with the attribute value, AttxVal, field being a CHAR(*) value. The AttxValLn field should be set to the length of the attribute value.
  • The subcommand field, AttxSubcmd, controls whether this service call will set or remove the attribute. If GET, LIST, or any other value is specified, then the call will fail with JRInvAttxCmd.
  • AttxFlags, AttxfReplace, and AttxfCreate are used to validate the request against the extended attribute. AttxfReplace checks if the attribute is set and can be replaced. If it is not set, this service call returns reason code JrAttxUnavail. AttxfCreate checks if the attribute is not set and able to be created (set). If it is already set, BPX1CHR/BPX4CHR returns reason code JrAttxExists.
  • The AttxfLset flag controls whether the operation affects a symlink’s attributes or the attributes of the symlink’s target. When this flag is ON, the operation affects the symlink. When the flag is OFF, the operation affects the symlink’s target.
  • The SET/REMOVE function affects the attribute information that also exists in BPXYSTAT. The following table provides a correspondence between the information in BPXYATT and BPXYSTAT.
    Table 1. Correspondence between BPXYATT and BPXYSTAT
    Xattr name Existing SET attribute in BPXYATT Existing GET attribute in BPXYSTAT Restrictions and comments
    trusted.apfauth attapfauth ST_APFAUTH Set and remove functions that are limited according to “general flags” restrictions.
    trusted.sharelib attsharelib ST_SHARELIB Set and remove functions that are limited according to “general flags” restrictions.
    trusted progctl attprogctl ST_PROGCTL Set and remove functions that are limited according to “general flags” restrictions.
    system.noshareas attnoshareas ST_NOSHAREAS Set and remove functions that are limited according to “general flags” restrictions.
    system.filefmt attfilefmt ST_FILEFMT None.
    system.filetag attfiletag ST_FILETAG None.
    system.seclabel attseclabel ST_SECLABEL None.
    system.useraudit attuseraudit ST_USERAUDIT None.
    system.auditoraudit attauditoraudit ST_AUDITORAUDIT None.
    system.auditid Not an attribute. Equivalent to field ST_AUDITID in BPXYSTAT. ST_AUDITID Read-only.
    system.dmodelacl Not an attribute. Equivalent to field. ST_DMODELACL Read-only.
    system.fmodelacl Not an attribute. Equivalent to field. ST_FMODELACL Read-only.
    system.accessacl Not an attribute. Equivalent to field. ST_ACCESSACL Read-only.
    system.createtime Not an attribute. Equivalent to field. ST_CREATETIME Read-only.
    user.* No equivalent. No equivalent. Needs specific PFS support.

Usage notes

Table 2. 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.
  1. 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 2. Multiple attributes can be changed at the same time.

    Clear the Set Flag field before turning on any bits. It is an error if any of the reserved bits in the flag field are turned on.

  2. 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 2) for a detailed description.
  3. Changing mode (ATTMODECHG = ON):
    • The file mode field in Attributes is mapped by the BPXYMODE macro (see BPXYMODE — Map the mode constants). For information about 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. The caller will seem 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 the caller does not have appropriate privileges and 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.
  4. 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.

  5. Changing General Attribute bits (ATTSETGEN = ON):
    • For General Attribute bits to be changed, the calling process must have write permission for the file.
  6. 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.
  7. Changing times:
    • All of the 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 the 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.
  8. 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.

  9. 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.
  10. 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.
  11. 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.
  12. 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

  1. The ATTEXTLINK flag in the ATTGENVALUE field of BPXYATT cannot be modified with BPX1CHR (BPX4CHR).
  2. 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

See BPX1CHR (chattr) example and BPX4CHR (chattr) example.