Sends a message on a stream.
int putmsg (fd, ctlptr, dataptr, flags) int fd; struct strbuf *ctlptr; struct strbuf *dataptr; int flags;
The putmsg system call creates a message from user-specified buffers and sends the message to a STREAMS file. The message may contain either a data part, a control part or both. The data and control parts to be sent are distinguished by placement in separate buffers. The semantics of each part is defined by the STREAMS module that receives the message.
Note: To use the putmsg system call you must import the /lib/pse.exp file during the compile. For example, compile the system call using the following command:cc -bI:/lib/pse.exp
statement. Failure to import this file means that the putmsg system call will be unresolved during the link edit phase.
|fd||Specifies a file descriptor referencing an open stream.|
|ctlptr||Holds the control part of the message.|
|dataptr||Holds the data part of the message.|
|flags|| Indicates the type of message to be sent. Acceptable values are:
The ctlptr and dataptr parameters each point to a strbuf structure that contains the following members:
int maxlen; /* not used */ int len; /* length of data */ char *buf; /* ptr to buffer */
The len field in the strbuf structure indicates the number of bytes to be sent, and the buf field points to the buffer where the control information or data resides. The maxlen field is not used in the putmsg system call.
To send the data part of a message, the dataptr parameter must be nonnull and the len field of the dataptr parameter must have a value of 0 or greater. To send the control part of a message, the corresponding values must be set for the ctlptr parameter. No data (control) part will be sent if either the dataptr (ctlptr) parameter is null or the len field of the dataptr (ctlptr) parameter is set to -1.
If a control part is specified, and the flags parameter is set to RS_HIPRI, a priority message is sent. If the flags parameter is set to 0, a nonpriority message is sent. If no control part is specified and the flags parameter is set to RS_HIPRI, the putmsg system call fails and sets the errno global variable to EINVAL. If neither a control part nor a data part is specified and the flags parameter is set to 0, no message is sent and 0 is returned.
For nonpriority messages, the putmsg system call blocks if the stream write queue is full due to internal flow-control conditions. For priority messages, the putmsg system call does not block on this condition. For nonpriority messages, the putmsg system call does not block when the write queue is full and the O_NDELAY flag is set. Instead, the system call fails and sets the errno global variable to EAGAIN.
The putmsg system call also blocks, unless prevented by lack of internal resources, while waiting for the availability of message blocks in the stream, regardless of priority or whether the O_NDELAY flag has been specified. No partial message is sent.
Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.
The putmsg system call fails if one of the following is true:
|EAGAIN||A nonpriority message was specified, the O_NDELAY flag is set, and the stream write queue is full due to internal flow-control conditions.|
|EAGAIN||Buffers could not be allocated for the message that was to be created.|
|EBADF||The value of the fd parameter is not a valid file descriptor open for writing.|
|EFAULT||The ctlptr or dataptr parameter points outside the allocated address space.|
|EINTR||A signal was caught during the putmsg system call.|
|EINVAL||An undefined value was specified in the flags parameter, or the flags parameter is set to RS_HIPRI and no control part was supplied.|
|EINVAL||The stream referenced by the fd parameter is linked below a multiplexer.|
|ENOSTR||A stream is not associated with the fd parameter.|
|ENXIO||A hangup condition was generated downstream for the specified stream.|
|ERANGE||The size of the data part of the message does not fall within the range specified by the maximum and minimum packet sizes of the topmost STREAMS module.|
|The control part of the message is larger than the maximum configured size of the control part of a message.|
|The data part of a message is larger than the maximum configured size of the data part of a message.|
The putmsg system call also fails if a STREAMS error message was processed by the stream head before the call. The error returned is the value contained in the STREAMS error message.
This system call is part of STREAMS Kernel Extensions.
|/lib/pse.exp||Contains the STREAMS export symbols.|
The getmsg system call, getpmsg system call, putpmsg system call.
The read subroutine, poll subroutine, write subroutine.
List of Streams Programming References and STREAMS Overview in AIX Version 4.3 Communications Programming Concepts.