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)

Threadsafe: Conditional; see Usage Notes.

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.

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;
         ssize_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

writev() returns an integer. Possible values are:

• -1 (unsuccessful)

• n (successful), where n is the number of bytes written.

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.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

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.

If writing to a socket, this error code indicates one of the following:

• The destination address specified is a broadcast address and the socket option SO_BROADCAST was not set (with a setsockopt()).

• The process does not have the appropriate privileges to the destination address. This error code can only be returned on a socket with an address family of AF_INET and a type of SOCK_DGRAM.

[EAGAIN]

Operation would have caused the process to be suspended.

[EBADF]

Descriptor not valid.

A file descriptor argument was out of range, referred to a file that was not open, or a read or write request was made to a file that is not open for that operation.

A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or does not refer to an open file. Or this writev() request was made to a file that was only open for reading.

[EBADFID]

A file ID could not be assigned when linking an object to a directory.

The file ID table is missing or damaged.

To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible.

[EBUSY]

Resource busy.

An attempt was made to use a system resource that is not available at this time.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EFBIG]

Object is too large.

The size of the object would exceed the system allowed maximum size.

The file is a regular file, nbyte is greater than 0, and the starting offset is greater than or equal to 2GB minus 2 bytes.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

The file resides in a file system that does not support large files, and the starting offset exceeds 2GB minus 2 bytes.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function.

[ENOSPC]

No space available.

The requested operations required additional space on the device and there is no space left. This could also be caused by exceeding the user profile storage limit when creating or transferring ownership of an object.

Insufficient space remains to hold the intended file, directory, or link.

[ENOTSAFE]

Function is not allowed in a job that is running with multiple threads.

[ETRUNC]

Data was truncated on an input, output, or update operation.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

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

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

This error code can only be returned on sockets that use a connectionless transport service.

[EDESTADDRREQ]

Operation requires destination address.

A destination address has not been associated with the socket pointed to by the fildes parameter. This error code can only be returned on sockets that use a connectionless transport service.

[EHOSTDOWN]

A remote host is not available.

This error code can only be returned on sockets that use a connectionless transport service.

[EHOSTUNREACH]

A route to the remote host is not available.

This error code can only be returned on sockets that use a connectionless transport service.

[EINTR]

Interrupted function call.

[EMSGSIZE]

Message size out of range.

The data to be sent could not be sent atomically because the size specified by nbyte is too large.

[ENETDOWN]

The network is not currently available.

This error code can only be returned on sockets that use a connectionless transport service.

[ENETUNREACH]

Cannot reach the destination network.

This error code can only be returned on sockets that use a connectionless transport service.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOTCONN]

Requested operation requires a connection.

This error code can only be returned on sockets that use a connection-oriented transport service.

[EPIPE]

Broken pipe.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EWOULDBLOCK]

Operation would have caused the thread to be suspended.

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

[EADDRNOTAVAIL]

Address not available.

[ECONNABORTED]

Connection ended abnormally.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[EHOSTDOWN]

A remote host is not available.

[EHOSTUNREACH]

A route to the remote host is not available.

[ENETDOWN]

The network is not currently available.

[ENETRESET]

A socket is connected to a host that is no longer available.

[ENETUNREACH]

Cannot reach the destination network.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

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.

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:

   • There are secondary threads active 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

     • QOPT

     • QLANSrv

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. 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.

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

• fcntl()--Perform File Control Command

• fcntl()--Retrieve or Change Descriptor Attributes

• ioctl()--Change Descriptor Attributes

• ioctl()--Perform File 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

• send()--Send Data

• write()--Write to Descriptor