putmsg, putpmsg - send message to STREAMS file

Syntax	#include <stropts.h> int putmsg(int fildes, const struct strbuf *ctlptr, const struct strbuf *dataptr, int flags); int putpmsg(int fildes, const struct strbuf *ctlptr, const struct strbuf *dataptr, int band, int flags);
Description	putmsg() creates a message from the specified buffers and sends it to a STREAMS file. The message can contain either a data section, a control section or both. The data and control sections to be sent are distinguished from each other by being written to different buffers (see below). The semantics of the sections is defined via the STREAMS module that receives the message. The putpmsg() function has the same functionality as putmsg(), but it allows the user to send messages with different priorities. All information described here for putmsg() also applies to putpmsg(), with exceptions being explicitly indicated. fildes is a file descriptor that references an open stream. ctlptr and dataptr each point to an strbuf structure containing the following elements: int maxlen; /* Not used */ int len; /* Length of data */ void *buf; /* Pointer to buffer for data */ ctlptr points to the structure that describes the control section to be included in the message (if there is one). The buf field in the strbuf structure points to the buffer containing the control information, and the len field specifies the number of bytes to be sent. The maxlen field is not used in putmsg() (see getmsg()). In the same way, dataptr describes the data section which is to be included in the message. flags indicates what type of message is to be sent (see below). For the data section of a message to be sent, dataptr must not be the same as the null pointer, and the len field of dataptr must contain a value ≥ 0. For the control section of a message to be sent, the corresponding values must be set for ctlptr. A data (control) section is not sent if either dataptr (ctlptr) is the null pointer or the corresponding len field is set to -1. If a control section is specified in putmsg(), and flags is set to RS_HIPRI, a message with high priority is sent. If no control section is specified and flags is set to RS_HIPRI, putmsg() fails and sets errno to EINVAL. If flags is set to 0, a normal message is sent (priority=0). If neither a control section nor a data section is specified and flags is set to 0, no message is sent and the value 0 is returned. The STREAM head guarantees that the control section of a message generated by putmsg() is at least 64 bytes long. Other flags are used for putpmsg(): flags is a bit mask which contains either MSG_HIPRI or MSG_BAND or 0 (the values mutually exclude each other). If flags is set to 0, putpmsg() fails and sets errno to EINVAL. If a control section is specified and flags is set to MSG_HIPRI and band is set to 0, a message with a high priority is sent. If flags is set to MSG_HIPRI, and either no control section is specified or band != 0, putpmsg() fails and sets errno to EINVAL. If flags is set to MSG_BAND, a message in the priority class specified by band is sent. If no control section and no data section are specified, and flags is set to MSG_BAND, no message is sent and 0 is returned. Normally, putmsg() blocks if the read/write queue of the stream is full because of internal control flow conditions. With high-priority messages, however, putmsg() does not block in this case. With other messages, putmsg() does not block if the read/write queue is full if O_NDELAY or O_NONBLOCK is set. Instead, the call fails and errno is set to EAGAIN. putmsg() or putpmsg() block regardless of the priority and O_NDELAY or O_NONBLOCK even if they are waiting for the availability of message blocks in the stream. Partial messages are not sent.
Return val.	0	if successful.
	-1	if an error occurs. errno is set to indicate the error.
Errors	putmsg() and putpmsg() will fail if:
	EAGAIN	A message without priority was specified, the O_NDELAY or O_NONBLOCK flag is set, and the read/write queue of the STREAM is full because of internal control flow conditions or no buffer could be allocated for the message to be created.
	EBADF	fildes is not a valid file descriptor open for writing.
	EINTR	A signal was caught during the putmsg() system call.
	EFAULT	ctlptr or dataptr point outside the allocated address space.
	EINVAL	An undefined value was specified in flags or flags is set to RS_HIPRI or MSG_HIPRI and no control section was provided or the STREAM or multiplexer referenced by fildes is connected downstream via a multiplexer. For putpmsg() only: flags is set to MSG_HIPRI and band != 0.
	ENOSR	No buffer could be allocated for the message to be created because there was not enough STREAMs storage space.
	ENOSTR	No STREAM belongs to fildes.
	ENXIO	A hang-up was generated downstream for the specified stream.
	EPIPE or EIO
		fildes references a STREAM-based pipe and the other end of the pipe is closed. The SIGPIPE signal is generated for the calling process.
	ERANGE	The data section of the message has a size that is not within the range defined by the maximum and minimum packet size of the highest stream module. ERANGE is also returned if the control section of the message is larger than the configured maximum size of the control section of a message, or if the data section of a message is larger than the configured maximum size of the data section of a message.
	putmsg() and putpmsg() also fail if an asynchronous STREAMs error message has reached the stream head before the putmsg() or putpmsg() call. In this case, errno refers to the error contained in the STREAMS error message.
Notes	If two processes open a FIFO file, with one writing a high-priority message with putmsg() and the other reading a high-priority message with getmsg(), messages can be lost. This loss can be avoided by slowing down the send process with sleep between the individual putmsg() calls.
See also	getmsg(), poll(), read(), write(), stropts.h.