Technical Reference: Communications, Volume 2

putmsg System Call

Purpose

Sends a message on a stream.

Syntax

#include <stropts.h>

int putmsg (fd, ctlptr, dataptr, flags) int fd; struct strbuf * ctlptr; struct strbuf * dataptr; int flags;

Description

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.

This system call is part of STREAMS Kernel Extensions.

Parameters

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: 0 Sends a nonpriority message. RS_HIPRI Sends a priority message.

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 or O_NONBLOCK 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 or O_NONBLOCK flag has been specified. No partial message is sent.

Return Values

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.

Error Codes

The putmsg system call fails if one of the following is true:

Value	Description
EAGAIN	A nonpriority message was specified, the O_NONBLOCK 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.
ENOSR	Buffers could not be allocated for the message that was to be created due to insufficient STREAMS memory resources.
ENOSTR	A stream is not associated with the fd parameter.
ENXIO	A hangup condition was generated downstream for the specified stream.
EPIPE or EIO	The fd parameter refers to a STREAM-based pipe and the other end of the pipe is closed. A SIGPIPE signal is generated for the calling thread.
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.
	OR
	The control part of the message is larger than the maximum configured size of the control part of a message.
	OR
	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.

Files

/lib/pse.exp

Contains the STREAMS export symbols.

Related Information

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 5L Version 5.2 Communications Programming Concepts.