vn_trunc — Truncate a file

Function

The vn_trunc operation changes the length of an open file.

Environment on entry and exit

vn_trunc     (Token_structure,
              OSI_structure,
              Audit_structure,
              File_length,
              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. See OSI services for more information.

It also contains MVS-specific information that needs to 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 details on 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.

File_length

Supplied parameter

Type:: Integer
Length:: Doubleword

A doubleword that contains the number of bytes to which the file size is to be set. Only positive values are passed by the caller.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_trunc operation returns the results of the operation, as one of the following:

Return_value: Meaning
-1: The operation was not successful. The Return_code and Reason_Code values must be filled in 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_trunc operation stores the return code. The vn_trunc operation returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of supported return code values.

The vn_trunc operation should support at least the following error value:

Return_code	Explanation
EROFS	The file is on a read-only file system.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_trunc operation stores the reason code. The vn_trunc 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_trunc processing

The vn_trunc changes the file size to File_length bytes.

Specific processing notes

The difference between vn_trunc and vn_setattr(truncate) is that vn_trunc is called for ftruncate(), and therefore does not do a security check. vn_setattr(truncate) is called for truncate() and must do a security check.
When a file is truncated, all data from File_length to the original end of the file must be removed.
Full blocks are returned to the file system so that they can be used again, and the file size must be changed to the lesser of File_length or the current length of the file.
When the file is expanded, its length is changed to File_length and unwritten bytes read between the old end-of-file and the new end-of-file are returned as zeros.
The LFS ensures that the file is a regular file, open for writing if necessary, and that the File_length is not negative.
When the file size is changed successfully, the PFS calls SAF's Clear Setid callable service.
The LFS enforces any file size limits that may be in effect.
Refer to the ftruncate() function in the POSIX .1a standard (IEEE Std 1003.1a), draft 7, for more information about the semantics of this operation for a POSIX-conforming PFS.

Serialization provided by the LFS

The vn_trunc operation is invoked with an exclusive latch held on the vnode of the directory.

Security calls to be made by the PFS

Clear Setid.

Related services

vn_open — Open a file