Getting and setting attributes

The PFS is responsible for storing file attributes with its files. POSIX users can read these attributes with such functions as stat(), and set various attributes through such functions as chmod(). A VFS server does the same things with v_getattr() and v_setattr().

All of this is passed through to the PFS when the LFS calls the vn_getattr or vn_setattr service with the ATTR structure (BPXYATTR). The ATTR structure is the file attribute interface between the LFS and the PFS. It contains all the fields of the POSIX STAT structure, plus z/OS UNIX extensions that the PFS may support if it can.

A file's attributes are logically split between the security-related and non-security-related attributes. The security-related attributes are kept in the file security packet, IRRPIFSP, or FSP for short. The FSP is stored with the attributes of the file by the PFS, but it is created and changed only through SAF-defined routines. The FSP contains the file's mode bits, UID, and GID; it may also contain other information that is defined by the security product.

The FSP is the file attribute interface between the PFS and SAF. Refer to Security responsibilities and considerations and Creating files for more details on SAF and the FSP.

Serialization: The vn_getattr service is invoked with a shared vnode latch, and the vn_setattr service with an exclusive latch.

vn_getattr and vn_setattr do not require vn_open, although the file may be open for read or write at the time of these calls. Reads and writes would not be in progress at the time of the get or set.

All times in the ATTR structure are specified in POSIX format, which is "Seconds Since the Epoch" (00:00:00 January 1, 1970, Coordinated Universal Time). The PFS may keep time values internally in any format, but they must be in POSIX format across the LFS-PFS interface.

The ATTR structure's header is initialized with the ATTR's length before any get or set call.

The vn_getattr protocol is as follows:

All ATTR fields that are supported by the PFS are returned.
To account for different release levels, the PFS should zero out the area and set fields it understands only up to the minimum of the input area's length (from the ATTR length subfield) and the PFS's native ATTR length (the one it was compiled with). The input area's ATTR length subfield should be updated to reflect the amount of data that is returned or zeroed out.
A simple way to do this is to construct a local ATTR structure and copy this, truncating it if necessary, to the input ATTR.

The vn_setattr protocol is as follows:

More than one attribute may be changed on a single vn_setattr call, and each settable field in the ATTR structure is conditionally and individually set. Bit flags are set by the LFS in an ATTR flag area to indicate which fields from the ATTR structure are being set.
- In general, if a change bit is on, the PFS updates the corresponding file attribute from the value that is passed in the corresponding ATTR field.
- Security fields. For each security-related field, such as mode, owner, or audit, that is being changed, there is a corresponding SAF routine that the PFS calls to actually make the changes in the FSP. This allows the security product to do permission checks and security auditing, or other necessary security-related processing.
- Time fields. Two bits are defined for each time field. The first bit indicates that a change is to be made, and the second bit indicates whether to use the corresponding ATTR time field's value, or if the current time of day is to be generated and stored by the PFS.
Non-security fields may still have access control defined for them. This means that SAF is called to see if the user has permission to make the change, but the PFS does the change.
The PFS should ensure that either all changes or no changes are permanently recorded for a single vn_setattr call.
To account for different release levels, the PFS must not refer to fields beyond the input ATTR's length, as specified in its length subfield.

Note: To optimize performance for VFS servers, several of the vnode operations, such as vn_lookup and vn_rdwr, pass an ATTR structure pointer in the OSI structure and expect an implicit vn_getattr to be performed at the end of the current operation. If the PFS cannot support this, the LFS calls vn_getattr after the operation in question. This flow has poorer performance when accessing files owned by this PFS.