vn_setattr — Set the attributes of a file

Function

The vn_setattr operation sets the attributes of a file.

Environment on entry and exit

Input parameter format

vn_setattr  (Token_structure,
             OSI_structure,
             Audit_structure,
             attribute_structure,
             Return_value,
             Return_code,
             Reason_code)

Parameters

Token_structure

Supplied parameter

Type:: TOKSTR
Length:: Specified by TOKSTR.ts_hdr.cblen.

The Token_structure represents the file (vnode) that is being operated on. It contains the PFS's initialization token, mount token, and the file token. Refer to LFS/PFS control block structure for a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI in Interface structures for C language servers and clients for its mapping.

OSI_structure

Supplied and returned parameter

Type:: OSI
Length:: Specified by OSI.osi_hdr.cblen.

The OSI_structure contains information that is used by the OSI operations that may be called by the PFS. For more information, see OSI services.

It also contains MVS-specific information that must be passed to the PFS, including SMF accounting fields, a work area, a recovery area, and an optional pointer to an output ATTR structure. For more information about the OSI structure, see The OSI structure.

This area is mapped by the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.

Audit_structure

Supplied parameter

Type:: CRED
Length:: Specified by CRED.cred_hdr.cblen.

The Audit_structure contains information that is used by the security product for access checks and auditing. It is passed to most SAF routines that are invoked by the PFS.

Refer to Security responsibilities and considerations for a discussion of security processing, and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for the mapping of this structure.

attribute_structure

Supplied parameter

Type:: ATTR
Length:: Specified by ATTR.at_hdr.cblen.

An area that contains the file attributes that are to be set for the file that is specified by the vnode token. This area is mapped by typedef ATTR in the BPXYVFSI header file (see Interface structures for C language servers and clients).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_setattr operation returns the results of the operation, as one of the following error values:

-1: The operation was not successful. The Return_code and Reason_Code values must be completed by the PFS when Return_value is -1.
0: The operation was successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_setattr operation stores the return code. The vn_setattr operation returns Return_code only if Return_value is -1. For a complete list of supported return code values, see z/OS UNIX System Services Messages and Codes.

The vn_setattr operation should support at least the following error values:

Return_code	Explanation
EACCES	The caller does not have SAF authority to do these tasks:: Set the access time or modification time to current time Truncate the file
EPERM	The caller does not have SAF authority to do these tasks:: Change the mode Change the owner Change general attribute bits Set a time field to a value (not the current time) Set the change time or reference time to the current time Change the auditing flags Change the file format Set the security label; or there is already a security label that is associated with the file
EROFS	The file system is mounted read-only.
ENOSPC	The file system is out of space.
EINVAL	Incorrect input parameter, such as a negative time value, an incorrect mode field, or an incorrect UID-GID.

Reason_code

Returned parameter

Type:: Integer
Character set:: N/A
Length:: Fullword

A fullword in which the vn_setattr operation stores the reason code. The vn_setattr operation returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. These reason codes are documented by the PFS.

Implementation notes

Overview of vn_setattr processing

vn_setattr is used to set file attributes, as described in Getting and setting attributes.

Specific processing notes

Table 1. attribute_structure input fields
Set flags	Attribute fields input	Description
at_modechg	at_mode	Set the mode according to the value in at_mode
at_ownchg	at_uid at_gid	Set the owner user ID (UID) and group ID (GID) to the values specified in at_uid and at_gid
at_setgen	at_genvalue at_genmask	Only the bits corresponding to the bits set ON in the at_genmask are set to the value (ON or OFF) in at_genvalue; other bits are unchanged
at_trunc	at_sizeh at_size	Truncate the file size to the number of bytes specified by the doubleword at_sizeh and at_size
at_atimechg	at_atime	Set the access time of the file to the value specified in at_atime
at_atimechg and at_atimeTOD	None	Set the access time of the file to the current time
at_mtimechg	at_mtime	Set the modification time of the file to the value specified in at_mtime
at_mtimechg and at_mtimeTOD	None	Set the modification time of the file to the current time
at_aauditchg	at_aaudit	Set the security auditor's auditing flags to the value specified in at_aaudit
at_uauditchg	at_uaudit	Set the user's auditing flags to the value specified in at_uaudit
at_ctimechg	at_ctime	Set the change time of the file to the value specified in at_ctime
at_ctimechg and at_ctimeTOD	None	Set the change time of the file to the current time
at_reftimechg	at_reftime	Set the reference time of the file to the value specified in at_reftime
at_reftimechg and at_refTOD	None	Set the reference time of the file to the current time
at_filefmtchg	at_filefmt	Set the file format of the file to the value in at_filefmt
at_seclabelchg	at_seclabel	Set the initial security label of the file to the value in at_seclabel

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

Contains ATTR

ATTR.at_hdr.cblen

Specifies the length of attribute_structure.
Multiple attributes can be changed on a single vn_setattr call. The PFS should ensure that either all supported changes or no changes are permanently recorded for a single vn_setattr call.
Changing mode (at_modechg = ON):
- SAF's Change File Mode callable service is called to perform the necessary security checks and to actually make the change to the mode field in the FSP.
- The at_mode field is mapped by modes.h.
Note:
1. The file type, which is contained within at_mode, is not changed by the vn_setattr operation.
2. Files that are open when the vn_setattr service is called retain the access permission they had when the file was opened.
Changing owner (at_ownchg = ON):
- SAF's Change Owner and Group callable service is called to perform the necessary security checks and to update the owner or group fields in the FSP.
Note: When the UID or GID value is set to -1, the original value remains unchanged.
Changing general attribute bits (at_setgen = ON):
- SAF's Check Access callable service is called for Write access before the PFS changes the file's general attribute bits.
- For each bit ON in the genmask, the corresponding bit in the file's attributes is set to the value (ON or OFF) from the corresponding genvalue field.
Truncating a file (at_trunc = ON):
- SAF's Check Access is called for write access before the PFS changes the file's size.
- The truncation of a file changes the file size to the doubleword value that is represented by at_sizeh and at_size, beginning from the first byte of the file.
  - If the file is larger than the specified file size, the data from the specified size to the original end of the file is removed. Full blocks are returned to the file system to be used again.
  - If the file is shorter than the specified size, bytes between the old and new lengths are read as zeros.
- When the file size is changed, the PFS calls SAF's Clear Setid callable service.
Note:
1. The LFS handles enforcing file size limits for vn_setattr.
2. The truncate() function requires write permission to the file, whereas ftruncate() requires that the file be open for writing. The LFS handles this difference by calling vn_setattr for the former and vn_trunc for the latter when the file is open for writing.
Changing time fields (atime, mtime, ctime, and reftime):
- All time fields in the ATTR are in POSIX format.
- Each time field is controlled by a pair of bits: the chg bit and the TOD bit, as listed in Table 1.
  - The chg bit (for instance, at_atimechg) indicates that the corresponding time field is to be changed.
  - The TOD bit (for instance, at_atimeTOD) indicates whether the change is to an explicitly specified time (bit is off) or to the current time of day (bit is on).
- For a time change using an explicit time value, the SAF check file owner service is called to verify that the caller is the file owner or has appropriate privileges before the PFS changes the corresponding file time field.
- To set the time to the current time of day, SAF's Check Access must be called to check for write permission. If the caller does not have write permission, SAF's Check File Owner is called to verify that the caller is the file owner or has appropriate privileges. One of the SAF checks must succeed before the PFS will change the corresponding time field of the file.
Changing auditor audit flags (at_aauditchg = ON) or user audit flags (at_uauditchg = ON):
- SAF's Change Audit Options callable service is called to perform the necessary security checks and to update the corresponding audit field in the FSP.
Changing file format (at_filefmtchg = ON):
- SAF's Check File Owner is called before the PFS saves the new file format value.
When any attribute field is changed successfully, the file's change time is also updated.
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 in z/OS UNIX System Services Programming: Assembler Callable Services Reference), 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 successfully sets the security label if the SECLABEL class is active. If the SECLABEL class is not active, the request returns successfully, but the security label is not set.
- You can invoke the SAF IRRSSB00 callable service to set the security label.

Serialization provided by the LFS

The vn_setattr operation is invoked with an exclusive latch held on the vnode. Shared read support can be modified by the PFS in the OSI upon return from the vn_setattr operation.

Security calls to be made by the PFS

Refer to the previous notes for the security calls that are made for the various file attributes.

Related services

vn_getattr — Get the attributes of a file