Technical Reference: Base Operating System and Extensions, Volume 1

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:

The calling process does not have root user authority.
The effective user ID of the calling process does not match the user ID of the file.
The file is executable by the group (S_IXGRP) or others (S_IXOTH).

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

The file does not match the effective group ID or one of the supplementary group IDs of the process,
OR
The file is executable by the owner (S_IXUSR) or others (S_IXOTH).
Note

Clearing of the SetUserID and SetGroupID bits can occur even if the subroutine fails because the data in the file was modified before the error was detected.

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

Parameters

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:

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.

EFBIG

The current offset plus NumberOfBytes is exceeds the offset maximum established in the open file description associated with FileDescriptor.

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:

ETIMEDOUT

The connection timed out.

Related Information

The open, openx, or creat (open, openx, open64, creat, or creat64 Subroutine) subroutine, truncate or ftruncate subroutines.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.