fclear()--Write (Binary Zeros) to Descriptor

 #include <unistd.h>

 off_t fclear
   (int file_descriptor, off_t nbyte);    

The fclear() function writes nbyte bytes of binary zeros to the file associated with the file_descriptor. nbyte should not be greater than INT_MAX (defined in the <limits.h> header file). If it is, [EINVAL] will be returned. If nbyte is zero, fclear() simply returns a value of zero without attempting any other action.

If file_descriptor refers to a "regular file" (a stream file that can support positioning the file offset), fclear() begins writing binary zeros at the file offset associated with file_descriptor. A successful fclear() increments the file offset by the number of bytes written. If the incremented file offset is greater than the previous length of the file, the length of the file is set to the new file offset. An unsuccessful fclear() will not change the file offset. If the file_descriptor does not refer to a "regular file", [EINVAL] will be returned.

If O_APPEND (defined in the <fcntl.h> header file) is set for the file, fclear() does not set the file offset to the end of the file before writing the output. Instead, it begins writing binary zeros at the current file offset associated with the file_descriptor.

If fclear() is called such that nbyte plus the current file offset will cause the size of the file to exceed 2GB minus 1 bytes when the file is not opened for large file access, the system allowed maximum file size when the file is opened for large file access, or the process soft file size limit, [EFBIG] will be returned.

If fclear() is successful and nbyte is greater than zero, the change and modification times for the file are updated.

If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA specified, binary zeros are written to the file assuming they are in textual form. The data (binary zeros) is converted from the code page of the application, job, or system, to the code page of the file as follows:

• Only simple conversions are performed. That is, if one byte of binary zeros does not convert to one byte of binary zeros then [ENOTSUP] is returned.
• When clearing a physical file in the QSYS.LIB file system the fclear() should not be performed across a record boundary. If it is, [ETRUNC] will be returned.

Note: The conversion of binary zeros will always result in binary zeros.

There are some important considerations if O_CCSID was specified on the open().

• If an fclear() is performed when there are partial characters buffered internally due to a previous write(), the fclear() will fail with the [ENOTSUP] error.
  
  
• Because of the above consideration and because of the possible expansion or contraction of converted data, applications using the O_CCSID flag should avoid assumptions about data size and the current file offset.

If O_TEXTDATA was not specified on the open(), binary zeros are written to the file without conversion. The application is responsible for handling the data.

Note: When the fclear completes successfully, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of the file mode will be cleared. If the fclear() is unsuccessful, the bits are undefined.

Parameters

file_descriptor

(Input) The descriptor of the file to be cleared (write binary zeros).

nbyte

(Input) Indicates the number of bytes to clear (write binary zeros).

Authorities

No authorization is required.

Return Value

Error Conditions

If fclear() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

Additionally, if interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
     
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • QFileSvr.400
     • Network File System
   
   
2. QSYS.LIB and independent ASP QSYS.LIB File System Differences

   This function will fail with error code [ENOTSAFE] if the object on which this function is operating is a save file and multiple threads exist in the job.

   An fclear() request should not be done on a save file. If it is, unpredictable results may occur.

   A successful fclear() updates the change, modification, and access times for a database member using the normal rules that apply to database files. At most, the access time is updated once per day.

   
   
3. QOPT File System Differences

   The change and modification times of the file are updated when the file is closed.

   When writing to files on volumes formatted in Universal Disk Format (UDF), byte locks on the range being cleared are ignored.

4. Network File System Differences

   Local access to remote files through the Network File System may produce unexpected results due to conditions at the server. Once a file is open, subsequent requests to perform operations on the file can fail because file attributes are checked at the server on each request. If permissions on the file are made more restrictive at the server or the file is unlinked or made unavailable by the server for another client, your operation on an open file descriptor will fail when the local Network File System receives these updates. The local Network File System also impacts operations that retrieve file attributes. Recent changes at the server may not be available at your client yet, and old values may be returned from operations (several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data).

   Reading, writing, and clearing of files with the Network File System relies on byte-range locking to guarantee data integrity. To prevent data inconsistency, use the fcntl() API to get and release these locks.

5. QFileSvr.400 File System Differences

   This file system does not support fclear() or fclear64(), [ENOTSUP] will be returned.

6. QNTC File System Differences

   This file system does not support fclear() or fclear64(), [ENOTSUP] will be returned.

7. File System Differences

   File systems other than "root" (/), QOpenSys, user-defined, QNTC and QFileSvr.400 will be restricted to doing fclear()s no larger than 2GB minus 1 bytes. If this rule is violated [EINVAL] will be returned.

8. For the file systems that do not support large files, fclear() will return [EINVAL] if nbyte plus the file offset exceeds 2GB minus 1 bytes, regardless of how the file was opened. For the file systems that do support large files, fclear() will return [EFBIG] if nbyte plus the file offset exceeds 2GB minus 1 bytes and the file was not opened for large file access.
   
   
9. If the fclear() exceeds the process soft file size limit, signal SIFXFSZ is issued.

Related Information

• The <fcntl.h> file (see Header Files for UNIX-Type Functions)
• The <unistd.h> file (see Header Files for UNIX-Type Functions)
• creat()--Create or Rewrite File
• dup()--Duplicate Open File Descriptor
• dup2()--Duplicate Open File Descriptor to Another Descriptor
• fclear64()--Write (Binary Zeros) to Descriptor (Large File Enabled)
• fcntl()--Perform File Control Command
• ftruncate()--Truncate File
• ftruncate64()--Truncate File (Large File Enabled)
• ioctl()--Perform I/O Control Request
• lseek()--Set File Read/Write Offset
• open()--Open File
• pread()--Read from Descriptor with Offset
• pread64()--Read from Descriptor with Offset (large file enabled)
• pwrite()--Write to Descriptor with Offset
• pwrite64()--Write to Descriptor with Offset (large file enabled)
• read()--Read from Descriptor
• readv()--Read from Descriptor Using Multiple Buffers
• write()--Write to Descriptor
• writev()--Write to Descriptor Using Multiple Buffers

Example

See Code disclaimer information for information pertaining to code examples.

The following example clears a specific number of bytes in a file:

#include <unistd.h>
#include <stdio.h>

main() {
  int  fileDescriptor;
  off_t  ret;
  int  oflags = O_CREAT | O_RDWR;
  mode_t mode = S_IRUSR | S_IWUSR | S_IXUSR;

  if ((fileDescriptor = open("foo", oflags, mode)) < 0)
    perror("open() error");
  else {
    if ((ret = fclear(fileDescriptor,  10)) == -1)
      perror("fclear() error");
    else printf("fclear() cleared %d bytes.\n", ret);
    if (close(fileDescriptor)!= 0)
       perror("close() error");
    if (unlink("foo")!= 0)
       perror("unlink() error");
  }
}

Output:

fclear() cleared 10 bytes.

API introduced: V5R3