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.

Parameters

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:

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.

Implementation Specifics

This system call is part of STREAMS Kernel Extensions.

Files

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.1 Communications Programming Concepts, and X/OPEN Common Application Environment (CAE) Specification: System Interfaces and Headers, Issue 5 (2/97).