Makes a hole in a file.
Standard C Library (libc.a)
off_t fclear ( FileDescriptor, NumberOfBytes)
int FileDescriptor;
off_t NumberOfBytes;
off64_t fclear64 ( FileDescriptor, NumberOfBytes)
int FileDescriptor;
off64_t NumberOfBytes;
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:
OR
In the large file enabled programming environment, fclear is redefined to be fclear64.
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. |
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.
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. |