[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]
Base Operating System and Extensions Technical Reference, 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;
Note: The fclear64 subroutine applies to Version 4.2 and later releases.
off64_t fclear64 (FileDescriptor, NumberOfBytes)
int FileDescriptor;
off64_t NumberOfBytes;
Description
Note: The fclear64 subroutine applies to Version 4.2 and later releases.
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. |
Implementation Specifics
This subroutine is part of Base Operating System (BOS) Runtime.
Related Information
The open, openx, or creat subroutine, truncate or ftruncate subroutines.
Files, Directories, and File Systems for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.
[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]