fchattr (BPX1FCR, BPX4FCR) — Change the attributes of a file or directory by descriptor

Function

The fchattr 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 size, and file tag. It can also be used to set the initial security label for a file or directory. You identify the file by its file descriptor.

For the corresponding service using a path name, see chattr (BPX1CHR, BPX4CHR) — Change the attributes of a file or directory.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1FCR):	31-bit
AMODE (BPX4FCR):	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 BPX1FCR,(File_descriptor,
              Attributes_length,
              Attributes,
              Return_value,
              Return_code,
              Reason_code)

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

Attributes_length

Supplied parameter

Type:: Integer
Length:: Fullword

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

Attributes

Supplied parameter

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

The name of the area containing the attributes that you want to change. The area is mapped by BPXYATT. For information on 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 where the fchattr 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 fchattr service stores the return code. The fchattr 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 fchattr 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; 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 change the file size; the calling process does not have write permission for the file.
EBADF	The File_descriptor parameter is not a valid file descriptor.
EFBIG	Attempting to change the size of a file, the specified length is greater than the maximum file size limit for the process. 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. The following reason codes can accompany the return code: JrInvalidAtt, JrNegativeValueInvalid, JrTrNotRegFile, JrTrNegOffset, JrFileNotEmpty, and JrInvalidFileTag.
EMVSERR	An MVS™ environmental error has been detected. The following reason code can accompany the return code: JrSeclabelClassInactive.
ENOSYS	The function is not supported for the specified file. The following reason code can accompany the return code: JrNotSupportedForFileType.
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; 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, and the calling process does not have appropriate privileges. The calling process was attempting to change the general attribute bits, and the calling process does not have write permission for the file. The calling process was attempting to set a time value (not current time); the effective user ID 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 set the change time or reference time to current time, and the calling process does not have write permission for the file. The calling process was attempting to change auditing flags; 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, and 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	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 fchattr service stores the reason code. The fchattr 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 fchattr
Set flags	Attribute fields input	Description
ATTMODECHG	ATTMODE	Set the mode according to the value in ATTMODE. See fchmod (BPX1FCM, BPX4FCM) — Change the mode of a file or directory by descriptor.
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 will be 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 fchaudit (BPX1FCA, BPX4FCA) — Change audit flags for a file by descriptor.
ATTMUAUDIT	ATTUSERAUDIT	Set the User's auditing flags to the value specified in ATTUSERAUDIT. See fchaudit (BPX1FCA, BPX4FCA) — Change audit flags for a file by descriptor.
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 should be updated. To set an attribute, turn the corresponding Set Flag on, and set the corresponding Attributes Field according to Table 1. Multiple attributes can be changed at the same time.
Clear the Set Flag field before any bits are turned on. It is an error if any of the reserved bits in the flag field are turned on.
Some of the attributes changed by the fchattr 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 fchattr 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.
- Setting the set-group-ID-on-execution permission (in mode) means that when this file is run through the exec 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 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 one 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 size of a file (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 previously larger than ATTSIZE bytes, the data from ATTSIZE to the original end of file is removed. If the file was previously 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 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 changing of a file to ATTSIZE bytes, where ATTSIZE is greater than the soft file size limit for the process, will fail with EFBIG and the SIGXFSZ signal will be generated for the process.
- If write access is removed at some time after the File_descriptor was opened for writing, a change request will fail with EACCES. In such a case, a call to ftruncate (BPX1FTR, BPX4FTR) — Change the size of a file could be used to change the file size.
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 will be set.
- When any attribute field is changed successfully, the file's change time is updated as well.
Changing auditor audit flags (ATTMAAUDIT = ON):
- For auditor audit flags to be changed, the user must have auditor authority. 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.
  Auditor authority is established 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 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.
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 fchattr.
The General Attribute bits (set by ATTSETGEN, ATTGENMASK, and ATTGENVALUE fields) are not intended as a general-use programming interface to fchattr.
The security label (ATTSECLABELCHG) flag requires RACF SPECIAL authorization and appropriate privileges. 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 using this callable service, see BPX1FCR (fchattr) example.