writev()--Write to Descriptor Using Multiple Buffers

 #include <sys/types.h>
 #include <sys/uio.h>

 int writev(int descriptor,
            struct iovec *io_vector[],
            int vector_length)  

The writev() function is used to write data to a file or socket descriptor. writev() provides a way for the data that is going to be written to be stored in several different buffers (scatter/gather I/O).

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

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

Parameters

descriptor

(Input) The descriptor to which the data is to be written. The descriptor refers to either a file or a socket.

io_vector[]

(Input) The pointer to an array of type struct iovec. struct iovec contains a sequence of pointers to buffers in which the data to be written is stored. The structure pointed to by the io_vector parameter is defined in <sys/uio.h>.

      struct iovec {
         void      *iov_base;
         size_t   iov_len;
      }

iov_base and iov_len are the only fields in iovec used by sockets. iov_base contains the pointer to a buffer and iov_len contains the buffer length. The rest of the fields are reserved.

vector_length

(Input) The number of entries in io_vector.

Authorities

No authorization is required.

Return Value

Error Conditions

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

When the descriptor refers to a socket, errno could indicate one of the following errors:

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

Error Messages

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. writev() only works with sockets on which a connect() has been issued, since the call does not allow the caller to specify a destination address.

3. writev() is an atomic operation on sockets of type SOCK_DGRAM and SOCK_RAW in that it produces one packet of data every time it is issued. For example, a writev() to a datagram socket results in a single datagram.

4. To broadcast on an AF_INET socket, the socket option SO_BROADCAST must be set (with a setsockopt()).

5. When using a connection-oriented transport service, all errors except [EUNATCH] and [EUNKNOWN] are mapped to [EPIPE] on an output operation when either of the following occurs:
   • A connection that is in progress is unsuccessful.
     
   • An established connection is broken.

   To get the actual error, use getsockopt() with the SO_ERROR option, or perform an input operation (for example, read()).

6. For the file systems that do not support large files, writev() 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, writev() will return [EFBIG] if the starting offset exceeds 2GB minus 2 bytes and the file was not opened for large file access.

7. Error number [EINVAL] will be returned when the specified vector_length value is less than 1 or greater than IOV_MAX, where IOV_MAX is defined in <sys/uio.h> along with the iovec structure.
   
   
8. QFileSvr.400 File System Differences

   When connecting to a system at release V5R4M5 and earlier, QFileSvr.400 does not support large files. Otherwise, the starting offset is limited by the file system being accessed on the server.

9. QOPT File System Differences

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

10. QNTC File System Differences

    QNTC ignores any resource limits set using the setrlimit()--Set resource limit API when performing writev() operations.
    

11. 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 character special file. In addition, the change and modification times for the file are updated.

12. If the write 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
• 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
• 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

[ Back to top | UNIX-Type APIs | APIs by category ]