COHERENT manpages
This page displays the COHERENT manpage for putmsg() [Place a message onto a stream].
List of available manpages
Index
putmsg() -- System Call (libc) Place a message onto a stream #include <stropts.h> int putmsg (fd, ctlptr, dataptr, flags) int fd, flags; const struct strbuf *ctlptr, *dataptr; putmsg() creates a message from user-specified buffer (or buffers), and sends the message to a STREAMS file. The message can contain either a data part, a control part, or both. The data and control parts to be sent are distinguished by being placed in separate buffers, as described below. The semantics of each part are defined by the STREAMS module that receives the message. fd gives a file descriptor that identifies an open stream. ctlptr and dataptr each point to a structure of tyupe strbuf, which contains the following members: int len; /* Length of data */ void *buf; /* Pointer to buffer */ ctlptr points to the structure that describes the control part (if any) to be included in the message: buf points to the buffer wherein the control information resides, and len gives the number of bytes to be sent. Likewise, dataptr specifies the data (if any) to be included in the message. flags gives the message's type; it is described in detail below. To send the data part of a message, dataptr must not be NULL, and the value of dataptr.len must be no less than zero. To send the control part of a message, the corresponding values must be set for ctlptr. putmsg() does not send the data portion of the message if dataptr is set to NULL or dataptr.len equals -1; likewise, putmsg() does not send the control portion of the message if ctlptr is NULL or ctrlptr.len equals -1. If a control part is specified and flags equals RS_HIPRI, putmsg() sends a high-priority message. If no control part is specified and flags equals RS_HIPRI, putmsg() fails and sets errno to EINVAL. If flags is set to zero, putmsg() sends a message of normal priority. If neither the control part nor the data part is specified, and if flags is set to zero, putmsg() sends no message and returns zero. The stream head guarantees that the control part of a message generated by putmsg() is at least 64 bytes long. putmsg() usually blocks if the stream head's write queue is full due to internal flow-control conditions. For high-priority messages, putmsg() does not block on this condition. For other messages, putmsg() does not block when the write queue is full and you have set the mode on fd to O_NDELAY or O_NONBLOCK. putmsg() never sends a partial message. For details on O_NDELAY and O_NONBLOCK, see the Lexicon entry for open(). Upon successful completion, putmsg() returns zero. If something goes wrong, putmsg() returns -1 and sets errno to an appropriate value. putmsg() fails if any of the following conditions is true: -> A non-priority message was specified, the mode on fd was set to O_NDELAY or O_NONBLOCK, and the stream-write queue is full due to internal flow- control conditions. putmsg() sets errno to EAGAIN. -> fd is not a valid file descriptor. putmsg() sets errno to EBADF. -> ctlptr or dataptr contains an illegal address. putmsg() sets errno to EFAULT. -> Your application caught a signal while it was executing putmsg(). putmsg() sets errno to EINTR. -> flags contains an undefined value, or you set flags RS_HIPRI but did not supply a control part. putmsg() sets errno to EINVAL. -> The stream referenced by fd is linked below a multiplexor. putmsg() sets errno to EINVAL. -> putmsg() could not allocate buffers for the message it was to send due to insufficient STREAMS memory resources. putmsg() sets errno to ENOSR. -> fd does not identify a stream. putmsg() sets errno to ENOSTR. -> A hangup condition was generated downstream for the specified stream, or the other end of the pipe is closed. putmsg() sets errno to ENXIO. -> The size of the message's data portion does not fall within range of legal packet sizes set by topmost stream module, or its control portion exceeds the maximum configured size. putmsg() sets errno to ERANGE. putmsg() also fails if a STREAMS error message had been processed by the stream head before the call to putmsg() was executed. putmsg() returns the the value contained in the STREAMS error message. See Also getmsg(), libc, STREAMS