STREAMS-UX Programmer's Guide (February 2007)

STREAMS Mechanism and System Calls
Writing to a Stream
Chapter 2
21
Writing to a Stream
User applications can write to a stream or a STREAMS-based pipe using the write(2), putmsg(2), or
putpmsg(2) system call. The three function calls mirror the functionality of the corresponding message
retrieval functions read(2), getmsg(2), and getpmsg(2). These system calls are described in the “Reading
From a Stream” on page 25.
The write(2) and writev(2) System Calls
A user application can write data to a stream using the write(2) and the writev(2) system calls.
Synopsis
#include <unistd.h>
ssize_t write(int fd, const void *buf, int nbytes);
#include <sys/uio.h>
ssize_t writev(int fd, const struct iovec *iov, int iovcnt);
Arguments
fd STREAMS device file descriptor.
buf Pointer to a buffer containing the data to be written to the stream.
nbytes Number of bytes to be written.
iov An array of struct iovec (io vectors) that contain the data to be written.
iovcnt Number of elements in the previous array.
Return Values
Upon successful completion, write(2) or writev(2) will return the number of bytes written to the stream.
This number does not exceed the value specified in the nbytes argument. If writev(2) fails for any reason,
-1 is returned and errno is set to the appropriate value.
writev(2)is similar to write(2), except that it writes data from buffers (io vectors) specified by members of
the iov array (iov[0], iov[1], ..., iov[iovcnt-1]). iovcnt is valid if its value is greater than 0 and less than
or equal to {IOV_MAX}, defined in <limits.h>. The iovec structure consists of a base address (iov_base)
and a byte length (iov_len) of an area in memory to be written. The writev(2) function always writes from
one iovec member completely before moving on to the next. The iovec structure is as follows:
struct iovec {
void *iov_base; /* Starting address */
size_t iov_len; /* Number of bytes */
};
Message Priority
The write(2) system call can only write data messages to a stream. Data messages are always written as
normal messages.
Maximum Packet Size Limit
The value of nbytes must fall within the acceptable STREAMS packet size range. STREAMS imposes two
levels of constraints for writing messages. The maximum sizes of a STREAMS data message and a STREAMS
control message are defined by STRMSGZSZ and STRCTLSZ respectively.