pwrite()--Write to Descriptor with Offset

 #include <unistd.h>

 ssize_t pwrite
   (int file_descriptor, const void *buf,
    size_t nbyte, off_t offset);  

The pwrite() function writes nbyte bytes from buf to the file associated with file_descriptor. The offset value defines the starting position in the file and the file pointer position is not changed.

See write()--Write to Descriptor for more information relating to writing to a descriptor.

The offset will also be ignored if file_descriptor refers to a descriptor obtained using the open() function with O_APPEND specified.

Parameters

file_descriptor

(Input) The descriptor of the file to which the data is to be written.

buf

(Input) A pointer to a buffer containing the data to be written.

nbyte

(Input) The size in bytes of the data to be written.

offset

(Input) The offset to the desired starting position in the file.

Authorities

No authorization is required.

Return Value

Error Conditions

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

If interaction with a file server is required to access the object, errno could also 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
     • Network File System
     • QFileSvr.400
   
   
2. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   For a physical file member opened in text mode, the offset must be equal to the current file position. Otherwise, this operation will fail with error code [EIO].

   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.

   If the file specified is a save file, only complete records will be written into the save file. A pwrite() request that does not provide enough data to completely fill a save file record will cause the partial record's data to be saved by the file system. The saved partial record will then be combined with additional data on subsequent pwrite()'s until a complete record may be written into the save file. If the save file is closed prior to a saved partial record being written into the save file, then the saved partial record is discarded, and the data in that partial record will need to be written again by the application.

   A successful pwrite() 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.

   You should be careful when writing end-of-file characters in the QSYS.LIB and independent ASP QSYS.LIB file systems. For these file systems, end-of-file characters are symbolic; that is, they are stored outside the file member. However, some situations can result in actual, nonsymbolic end-of-file characters being written to a member. These nonsymbolic end-of-file characters could cause some tools or utilities to fail. For example:
   
   

   • If you previously wrote an end-of-file character as the last character of a member, do not continue to write data after that end-of-file character. Continuing to write data will cause a nonsymbolic end-of-file to be written. As a result, a compile of the member could fail.
     
     
   • If you previously wrote an end-of-file character as the last character of a member, do not write other end-of-file characters preceding it in the file. This will cause a nonsymbolic end-of-file to be written. As a result, a compile of the member could fail.
     
     
   • If you previously used the integrated file system interface to manipulate a member that contains an end-of-file character, avoid using other interfaces (such as the Source Entry Utility or database reads and writes) to manipulate the member. If you use other interfaces after using the integrated file system interface, the end-of-file information will be lost.
     
     
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 written 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 and writing to 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

   The largest buffer size allowed is 16 megabytes. If a larger buffer is passed, the error EINVAL will be received.

6. For the file systems that do not support large files, pwrite() will return [EINVAL] if the starting offset exceeds 2GB minus 2 bytes, regardless of how the file was opened. For the file systems that do support large files, pwrite() will return [EFBIG] if the starting offset exceeds 2GB minus 2 bytes and the file was not opened for large file access.
   
   
7. Using this function successfully on the /dev/null or /dev/zero character special file results in a return value of the total number of bytes requested to be written. No data is written to the /dev/null or /dev/zero character special file. In addition, the change and modification times for the file are updated.
   
   
8. If the write exceeds the process soft file size limit, signal SIFXFSZ is issued.
   
   
9. If file_descriptor refers to a descriptor obtained using the open() function with O_TEXTDATA and O_CCSID specified, the file CCSID and open CCSID are not the same, and the converted data could expand or contract, then the offset value must be 0.
   
   
10. If file_descriptor refers to a character special file, the offset value is ignored.

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
• fclear()--Write (Binary Zeros) to Descriptor
• fclear64()--Write (Binary Zeros) to Descriptor (Large File Enabled)
• fcntl()--Perform File Control Command
• 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)
• pwrite64()--Write to Descriptor with Offset (large file enabled)
• read()--Read from Descriptor
• readv()--Read from Descriptor Using Multiple Buffers
• send()--Send Data
• sendmsg()--Send Data or Descriptors or Both
• sendto()--Send Data
• 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 writes a specific number of bytes to a file:

#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>

#define mega_string_len 1000000

main() {
  char *mega_string;
  int  file_descriptor;
  int  ret;
  off_t  off=5;
  char fn[]="write.file";

  if ((mega_string = (char*) malloc(mega_string_len+off)) == NULL)
    perror("malloc() error");
  else if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    memset(mega_string, '0', mega_string_len);
    if ((ret = pwrite(file_descriptor, mega_string, mega_string_len, off)) == -1)
      perror("pwrite() error");
    else printf("pwrite() wrote %d bytes at offset %d\n", ret, off);
    if (close(file_descriptor)!= 0)
       perror("close() error");
    if (unlink(fn)!= 0)
       perror("unlink() error");
  }
  free(mega_string);
}

pwrite() wrote 1000000 bytes at offset 5