fclear()--Write (Binary Zeros) to Descriptor
Syntax
#include <unistd.h> off_t fclear (int file_descriptor, off_t nbyte);
Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
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
value | fclear() was successful. The
return value is the number of bytes that have been
successfully cleared. This number will be equal to nbyte.
|
-1 | fclear() was not successful. The fclear() was not able to clear all of the bytes requested. No indication is given as to how much data was successfully cleared. In addition, the file offset will remain unchanged. The errno global variable is set to indicate the error. |
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.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EAGAIN] | |
[EBADF] | |
[EBADFID] | |
[EBUSY] | |
[ECONVERT] | |
[EDAMAGE] | |
[EFAULT] | |
[EFBIG] |
The size of the file would 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. |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[EJRNDAMAGE] | |
[EJRNINACTIVE] | |
[EJRNRCVSPC] | |
[ENEWJRN] | |
[ENEWJRNRCV] | |
[ENOMEM] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTSAFE] | |
[ENXIO] | |
[ERESTART] | |
[ETRUNC] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
Additionally, if interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFA081 E | Unable to set return value or error code. |
CPFA0D4 E | File system error occurred. Error number &1. |
Usage Notes
- 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
- Where multiple threads exist in the job.
- 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.
- 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.
- 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.
- QFileSvr.400 File System Differences
When connecting to a system at release V5R4M5 and earlier, QFileSvr.400 does not support fclear() or fclear64(), [ENOTSUP] will be returned. Otherwise, fclear() and fclear64() are supported but the size is limited by the file system being accessed on the server.
- QNTC File System Differences
This file system does not support fclear() or fclear64(), [ENOTSUP] will be returned.
- File System Differences
File systems other than "root" (/), QOpenSys, user-defined and QNTC will be restricted to doing fclear()s no larger than 2GB minus 1 bytes. If this rule is violated [EINVAL] will be returned.
- 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.
- 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
The following example clears a specific number of bytes in a file.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <unistd.h> #include <stdio.h> #include <fcntl.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