fclear or fclear64 Subroutine

Purpose

Makes a hole in a file.

Library

Standard C Library (libc.a)

Syntax

off_t fclear ( FileDescriptor,  NumberOfBytes)
int FileDescriptor;
off_t NumberOfBytes;

off64_t fclear64 ( FileDescriptor,  NumberOfBytes)
int FileDescriptor;
off64_t NumberOfBytes;

Description

The fclear and fclear64 subroutines zero the number of bytes specified by the NumberOfBytes parameter starting at the current file pointer for the file specified in the FileDescriptor parameter. If Network File System (NFS) is installed on your system, this file can reside on another node.

The fclear subroutine can only clear up to OFF_MAX bytes of the file while fclear64 can clear up to the maximum file size.

The fclear and fclear64 subroutines cannot be applied to a file that a process has opened with the O_DEFER mode.

Successful completion of the fclear and fclear64 subroutines clear the SetUserID bit (S_ISUID) of the file if any of the following are true:

This subroutine also clears the SetGroupID bit (S_ISGID) if:

In the large file enabled programming environment, fclear is redefined to be fclear64.

Parameters

Item Description
FileDescriptor Indicates the file specified by the FileDescriptor parameter must be open for writing. The FileDescriptor is a small positive integer used instead of the file name to identify a file. This function differs from the logically equivalent write operation in that it returns full blocks of binary zeros to the file system, constructing holes in the file.
NumberOfBytes Indicates the number of bytes that the seek pointer is advanced. If you use the fclear and fclear64 subroutines past the end of a file, the rest of the file is cleared and the seek pointer is advanced by NumberOfBytes. The file size is updated to include this new hole, which leaves the current file position at the byte immediately beyond the new end-of-file pointer.

Return Values

Upon successful completion, a value of NumberOfBytes is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The fclear and fclear64 subroutines fail if one or more of the following are true:

Item Description
EIO I/O error.
EBADF The FileDescriptor value is not a valid file descriptor open for writing.
EINVAL The file is not a regular file.
EMFILE The file is mapped O_DEFER by one or more processes.
EAGAIN The write operation in the fclear subroutine failed due to an enforced write lock on the file.
Item Description
EFBIG The current offset plus NumberOfBytes is exceeds the offset maximum established in the open file description associated with FileDescriptor.
Item Description
EFBIG An attempt was made to write a file that exceeds the process' file size limit or the maximum file size. If the user has set the environment variable XPG_SUS_ENV=ON prior to execution of the process, then the SIGXFSZ signal is posted to the process when exceeding the process' file size limit.

If NFS is installed on the system the fclear and fclear64 subroutines can also fail if the following is true:

Item Description
ETIMEDOUT The connection timed out.