Function

The v_setattr service sets the attributes that are associated with the file that is represented by Vnode_token. It can be used to change the mode, owner, access time, modification time, change time, reference time, audit flags, general attribute flags, and file size. It can also be used to set the initial security label for a file or directory.

Requirements

Parameters

Vnode_token

Supplied parameter

Type:

Token

Length:

8 bytes

The name of an 8-byte area that contains a vnode token that represents the file.

OSS

Supplied and returned parameter

Type:

Structure

Length:

OSS#LENGTH (from the BPXYOSS macro)

The name of an area that contains operating-system-specific parameters. This area is mapped by the BPXYOSS macro (see BPXYOSS — Map operating system specific information).

Attr_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of Attr. To determine the value of Attr_length, use the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Attr

Supplied and returned parameter

Type:

Structure

Length:

Specified by the Attr_length parameter

The name of an area, of length Attr_length, that contains the file attributes to be set for the file that is specified by the vnode token. The attributes of the file are also returned in this area, overlaying the input values. This area is mapped by the ATTR structure (see BPXYATTR — Map file attributes for v_ system calls).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_setattr 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 v_setattr service stores the return code. The v_setattr 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 v_setattr service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	Parameter error; for example, a supplied area was too small. The following reason codes can accompany the return code: JRSmallAttr, JRInvalidAttr, JRNegativeValueInvalid, JRTrNotRegFile, JRTrNegOffset, JRVTokenFreed, JRWrongPID, JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS.
EACCES	The calling process did not have appropriate permissions. Possible reasons include: In an attempt 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, and the process does not have appropriate privileges. In an attempt to truncate the file, the calling process does not have write permission for the file.
EFBIG	A process attempted to change the size of a file, but the new length that was specified is greater than the maximum file size limit for the process. The following reason code can accompany the return code: JRWriteBeyondLimit.
EPERM	The operation is not permitted for one of the following reasons: The caller of the service is not registered as a server. In an attempt 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. In an attempt to change the owner, the calling process does not have appropriate privileges. In an attempt to change the general attribute bits, the calling process does not have write permission for the file. In an attempt 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. In an attempt to set the change time or reference time to current time, the calling process does not have write permission for the file. In an attempt 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. In an attempt to change the security auditor's auditing flags, the user does not have auditor authority. In an attempt to set the security label, one or more of the following conditions applies: The calling process does not have RACF® SPECIAL authorization and appropriate privileges. The security label that is associated with the file is already set.
EROFS	The file is on a read-only file system. The following reason code can accompany the return code: JRReadOnlyFS.
ESTALE	On input, the AttrGuardTimeChk bit was on, and the input AttrGuardTime value did not match the Ctime of the file.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_setattr service stores the reason code. The v_setattr service returns 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

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

2. In addition to the attribute fields that are specified according to Table 1, the following ATTR header fields must be provided by the caller:

   ATTRID

   Contains ATTR.

   ATTRLEN

   Specifies the length of the ATTR structure.

   AttrGuardTimeChk

   Indicates whether the AttrGuardTime should be checked. If this bit is on, the PFS checks the Ctime of the file against the value that is specified in AttrGuardTime. If they do not match, the request fails with ESTALE.

   AttrGuardTime

   The time value, in seconds and micro-seconds, to be compared against the file's Ctime if AttrGuardTimeChk is set.

   Other fields in the ATTR should be set to 0s.

3. Changing mode (ATTRMODECHG = ON):
   • The file mode field in the ATTR area is mapped by the BPXYMODE macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).
   • Files that are open when the v_setattr 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.
4. Changing owner (ATTROWNERCHG = ON):
   • For changing the owner UID of a file, the caller must have appropriate privileges.
   • For changing 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 owner is changed, both UID and GID must be specified as they are to be set. If only one of these values is to be changed, the other must be set to its present value or to -1 in order to remain unchanged.
5. Changing general attribute bits (ATTRSETGEN = ON):
   • For general attribute bits to be changed, the calling process must have write permission for the file.
6. Truncating a file (ATTRTRUNC = ON):
   • The truncation of a file to ATTRSIZE bytes changes the file size to ATTRSIZE, beginning from the first byte of the file. If the file was originally larger than ATTRSIZE bytes, the data from ATTRSIZE to the original end of file is removed. If the file was originally shorter than ATTRSIZE, 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 truncated 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 authority to access the root.
   • Changing a file's size is considered to be a write operation and an open token from a prior v_open may be passed in the OSS to indicate that this change is being done within the open context of that token. Consequently, the operation does not have to be verified against the share reservations that may currently be in effect for the file. If no open token is available to pass on the call, there are three levels of share reservation checking that can be requested (see v_rdwr (BPX1VRW, BPX4VRW) — Read from and write to a file for details).
7. Changing times:
   • All time fields in the Attr area are in POSIX format.
   • For the access time or the modification time to be set explicitly (ATTRATIMECHG = ON or ATTRMTIMECHG = 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 (ATTRATIMETOD = ON or ATTRMTIMETOD = 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 (ATTRCTIMECHG = ON or ATTRREFTIMECHG = 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 (ATTRCTIMETOD = ON or ATTRREFTIMETOD = ON), the calling process must have write permission for the file.
   • When any attribute field is changed successfully, the file's change time is updated as well.
   • The setting of the AttrLP64times bit in the BPXYATTR structure, and not the AMODE of the caller, determines whether 4-byte or 8-byte time fields are used. When AttrLP64Times=ON with any of the explicit time changes the new time value is taken from the corresponding AttrATime64, AttrMTime64, AttrCTime64, or AttrRefTime64 field.
8. Changing auditor audit flags (ATTRMAAUDIT = 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 they do not have path access to or authority to use for other purposes.

     You can establish auditor authority by running the TSO/E command ALTUSER Auditor.

9. Changing user audit flags (ATTRMUAUDIT = ON):
   • For the user audit flags to be changed, the user must have appropriate privileges (See Authorization in z/OS UNIX System Services Programming: Assembler Callable Services Reference) or be the owner of the file.
10. Changing file format (ATTRFILEFMTCHG = ON):
    • The effective UID of the calling process must match the file's owner UID or the caller must have appropriate privileges.
11. Changing the security label (ATTSECLABELCHG=ON):
    • For the security label to be changed, the user must have RACF SPECIAL authorization and appropriate privileges, 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 SECLABEL class is active. If the SECLABEL class is not active, the request will return successfully, but the security label will not be set.
12. The tagging of /dev/null, /dev/random, /dev/urandom, /dev/zero is ignored.

Related services

• v_getattr (BPX1VGA, BPX4VGA) — Get the attributes of a file
• v_reg (BPX1VRG, BPX4VRG) — Register a process as a server

Characteristics and restrictions

1. A process must be registered as a server before the v_setattr service is permitted; see v_reg (BPX1VRG, BPX4VRG) — Register a process as a server.
2. The ATTREXTLINK flag in the ATTRGENVALUE field of the ATTR cannot be modified with BPX1VSA.
3. The general attribute fields (set by ATTRSETGEN, ATTRGENMASK, and ATTRGENVALUE fields) are not intended as a general-use programming interface on v_setattr.
4. The security label (ATTRSECLABELCHG) flag requires RACF SPECIAL authorization and appropriate privileges. See Authorization in z/OS UNIX System Services Programming: Assembler Callable Services Reference for information about appropriate privileges.
5. The security label (ATTRSECLABELCHG) flag cannot be used to change an existing security label; it can only be used to set an initial security label on a file.