zSetEOF

Syntax

#include <zPublics.h>

STATUS zSetEOF(
   Key_t   key,
   Xid_t   xid,
   QUAD    dataSizeBytes,
   NINT    setSizeFlags);

Parameters

key

(IN) Specifies the file (as returned by zOpen or zCreate) whose end of file will be changed.

xid

(IN) Specifies the transaction to which the request is bound. If the requested action is not part of a transaction, pass zNILXID.

dataSizeBytes

(IN) Specifies the logical byte offset in the file object at which the new end of file is to be set, which applies only to the data stream identified by key.

setSizeFlags

(IN) Specifies a bit mask that identifies various modes to the set data size function:

zSETSIZE_NON_ SPARSE_FILE	If this bit is not set and if the file size is being expanded, the file is expanded in a sparse manner with no data blocks being physically allocated to the file. If this bit is set and if the file size is being expanded, the file is expanded in a non-sparse manner, with data blocks being physically allocated to the file. The data block is also zeroed unless the zSETSIZE_NO_ZERO_FILL bit is set.
zSETSIZE_NO_ ZERO_FILL	If this bit is not set and if the file size is being expanded in a non-sparse manner, zero-filled data blocks are physically written to the file starting at the current end of file and ending at the new end of file. If this bit is set and if the file size is being expanded in a non-sparse manner, the new disk blocks allocated to the file are not zero-filled. The blocks are physically allocated to the file, but they are not initialized. This bit is allowed only from the NLM interface and cannot be set by an NCP that expands the file.
zSETSIZE_UNDO_ ON_ERR	If the file size is being expanded and if an error occurs anywhere during the expansion process, this bit is checked to determine the next action. If this bit is set, an error is returned and the file is restored to its original size as if no expansion took place. If this bit is not set, an error is returned and any partially completed expansion is left as part of the file.
zSETSIZE_ PHYSICAL_ONLY	If this bit is set, only the physical end of file is changed; the logical end of file is untouched. If the file is expanded with this option set, it is done in a non-sparse manner as if the zSETSIZE_NON_SPARSE_FILE bit were set. If the file is truncated with this bit set, the file is physically truncated, but the logical end of file remains unchanged.
zSETSIZE_ LOGICAL_ONLY	If this bit is set, zSetEOF does not touch physical storage, either to expand it or to truncate it. It only changes the logical end of file and leaves the physical storage that is allocated to the file unchanged.

Return Values

Remarks

zSetEOF modifies the data size (end of file) for the given open file object. If the file has more than one data stream, only the size of the data stream identified by the key is modified. All other data streams of the same file object are left unmodified. In order to modify the size of more than one data stream, each one must be opened independently and this function must be called once for each data stream.

If the new size is smaller than the existing size, the data at the end of the data stream is truncated and discarded.

If the new size is larger than the existing size, the data size is expanded. The file can be expanded in either a sparse or non-sparse manner. If setSizeFlags has the zSETSIZE_NON_SPARSE_FILE bit set, the file will be expanded in a non-sparse manner. If zSETSIZE_NO_ZERO_FILL is set, this non-sparse expanding is done without writing zeros. Otherwise, the file is expanded by physically writing zeros from the current size up to the new end of file.

If the zSETSIZE_NON_SPARSE_FILE bit is not set, the file will be expanded in a sparse manner with no data being actually written to the file. If a read operation is performed on sparse areas of a file, the read buffer is filled in with zeros.

If an error occurs during the process of expanding a file with zero-filled data, one of two possible actions takes place depending on the value of the zSETSIZE_UNDO_ON_ERR bit. If this bit is set, any partial expansions are unexpanded and the file is restored to its original state before the call was made. If this bit is not set and an error occurs partway through the expansion process, the partial expansion is left as part of the file with the rest of the expansion aborted.

See Also

zClose, zCreate, zFlush, zOpen, zRead, zWrite