OSF

NAME

putmsg − Send the message on the stream

SYNOPSIS

#include <stropts.h> int putmsg(
int fd,
struct strbuf ∗ctlbuf,
struct strbuf ∗databuf,
long ∗flags);

PARAMETERS

fdSpecifies a file descriptor that references an open stream. 

ctlptrPoints to a strbuf structure that holds the control part of the message.  See the DESCRIPTION section for more information. 

dataptrPoints to a strbuf structure that holds the data part of the message. See the DESCRIPTION section for more information. 

flagsPoints to an integer that specifies the type of message you want to send. 

DESCRIPTION

The putmsg() function generates a STREAMS message block using information from specified buffers.  This information is sent to the STREAMS file specified by the fd parameter. 

A message block must contain either a control part, data part, or both. The control part of the message block is placed into the buffer specified by the ctlptr parameter.  The data part of the message block is placed into the buffer specified by the dataptr parameter.  The STREAMS module that creates the message block also defines the semantics of the control and data parts. 

Effects of Parameters

The fd parameter specifies a file descriptor that references an open stream. 

The ctlbuf and databuf parameters point to separate strbuf structures that contain the following members:

int maxlen;/∗ maximum buffer length ∗/
int len;/∗ length of data ∗/
char ∗buf/∗ ptr to buffer ∗/

These fields are defined as follows:

FieldFunction

maxlenThis field is not used by the putmsg() function.  See getmsg(2) for information on this field. 

lenSpecifies the number of bytes to send. 

bufPoints to the buffers in which control or data information resides. 

The following conditions are possible:

       •If either ctlbuf or databuf is NULL, or the len field is set to -1, a STREAMS message block is not sent. 

       •If either ctrlbuf or databuf is not NULL, and the value of len is zero (0) or greater, a STREAMS message block is sent. 

The flags parameter points to an integer that specifies the type of message block you are able to send. 

By default, the putmsg() function processes the first available message on the stream head queue. However, if you set the flags parameter to RS_HIPRI, the putmsg() function sends the next message only if it is a high priority and only if ctlbuf is specified.  If the flags parameter is set to RS_HIPRI, and ctlbuf is not specified, the putmsg() functions fails and errno is set to EINVAL.  A specified data part may only be sent as RS_HIPRI if it includes a specified control part; otherwise, a specified data part may only be sent if the flags parameter is set to zero (0) and the priority is equal to zero (0).  If neither the control part or the data part are specified, and flags is set to zero (0), a message is not sent, and a value of zero (0) is returned. 

Unless a message is a high priority, the putmsg function blocks messages when a stream write queue is full because of internal flow control conditions.  For other messages, if O_NDELAY or O_NONBLOCK is set, messages are not blocked when the write queue is full; instead, the putmsg() function fails and errno is set to EAGAIN.  Regardless of the priority setting or the setting of O_NDELAY or O_NONBLOCK, putmsg() function blocks messages when waiting for the availability of messages in the stream (unless prevented by a lack of internal resources).  A partial message is not sent. 

RETURN VALUES

Upon successful completion, the putmsg() function returns a zero (0) value.  Otherwise, a value of -1 is returned and errno is set to indicate error. 

ERRORS

Following is a list of possible conditions and error settings:

[EAGAIN]May be one of the following:

The buffers are unavailable for the message that is being generated. 

The message is a nonpriority message, O_ONDELAY or O_NONBLOCK is set, and the stream write queue is full because of internal flow control conditions. 

[EBADF]The flags parameter is not a valid file descriptor open for writing. 

[EINTR]A signal was encountered during the putmsg() or putpmsg() operation. 

[EINVAL]May be one of the following:

An undefined value was specified by the flags parameter, or the flags parameter is specified as RS_HIPRI or MSG_HIPRI and a control part is not specified. 

The stream specified by the fd parameter is linked below a multiplexer. 

[ENOSTR]A stream is not associated with a fd parameter. 

[ENXIO]A hangup condition for the specified stream was encountered downstream. 

[ERANGE]The control or data parts of a message block exceeds their maximum configured size.  This condition is also returned if the data part size of the message does not conform to the range allowed by both the maximum and minimum packet sizes of the topmost stream module. 

If a STREAMS error messages is processed before a call was made to it, the putmsg() function fails.  The STREAMS error message specifies the error value returned. 

RELATED INFORMATION

Functions: getmsg(2), poll(2), read(2), write(2) Interfaces: streamio(7)