Content-type: text/html Man page of putmsg

putmsg

Section: System Calls (2)
Index Return to Main Contents
 

NAME

putmsg, putpmsg - Send a message on a Stream  

LIBRARY

Standard C Library (libc.so, libc.a)  

SYNOPSIS

#include <stropts.h>

int putmsg(        int fd,
       const struct strbuf *ctlbuf,
       const struct strbuf *databuf,
       int flags);

int putpmsg(        int fd,
       const struct strbuf *ctlbuf,
       const struct strbuf *databuf,
       int band,
       int flags);
 

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

putmsg(): XPG4-UNIX

putpmsg(): XPG4-UNIX

Refer to the standards(5) reference page for more information about industry standards and associated tags.  

PARAMETERS

Specifies a file descriptor that references an open Stream. Points to a strbuf structure that describes the control part, if any, of the message. This strbuf structure is described in the DESCRIPTION section. Points to a strbuf structure that holds the data part, if any, of the message. This strbuf structure is described in the DESCRIPTION section. Specifies the priority band. Specifies the type of message that should be sent.  

DESCRIPTION

The putmsg() and putpmsg() functions send messages to the STREAMS file. These messages are generated from user-provided buffer(s), and must contain a control part and/or a data part. The open Stream specifies the format and semantics of the message's control and data parts. The control and data parts of the message are placed into separate buffers, pointed at by cltbuf and databuf respectively. The putpmsg() function provides more control over how messages are sent. With this function, you can send messages in different priority bands. Except where specified, all information that applies to the putmsg() function also applies to the putpmsg() function.

The ctlbuf and databuf parameters each point to a strbuf structure that contains three members. This structure is defined in <sys/stropts.h> as:

struct strbuf {
    int maxlen;         /* max buffer length */

    int len;            /* length of data */

    char *buf           /* pointer to buffer */
}; The members are: Specifies the maximum number of bytes buf can hold. This field is not used by either the putmsg() or putpmsg() function. Points to the buffer where the control information is to reside. Specifies the number of bytes to be sent.

A message can contain a control part or a data part, or both, depending on what is to be sent. To send one or the other, the corresponding ctlbuf or databuf parameter must be a non-null pointer and the len field of the corresponding strbuf structure must have a value of 0 (zero) or greater. A data or control part is not sent if its respective databuf or ctlbuf parameter is a null pointer, or if the corresponding structure's len field is set to -1.

One of the major differences between the putmsg() and putpmsg() function, in addition to the band parameter, is how the flag parameter is used to send messages. The putmsg() function sends messages as follows: If you set the flags parameter to a value of 0 (zero), a normal message (priority band equal to 0 (zero)) is sent. If you set the flags parameter to RS_HIPRI and a control part is specified, the control and data (if present) is sent as a high priority message. If you set the flags parameter to RS_HIPRI and a control part is not specified, putmsg() fails. If you set the flags parameter to 0 (zero) and both the control part and the data part of not specified, no message is sent and a value of 0 (zero) is returned.

The putpmsg() function flags parameter is a bitmask with the mutually exclusive flags MSG_HIPRI and MSG_BAND defined. The putpmsg() function sends messages as follows: If you set flags to MSG_BAND, the control and/or data part is sent on the priority band specified by the band parameter. If you set the flags parameter to MSG_HIPRI, set the band parameter to 0 (zero), and specify a control part, the control and data (if present) is sent as a high-priority message. If you set the flags parameter to MSG_HIPRI, and either no control part is specified or band is set to a non-zero value, the putpmsg() function fails. If you set flags to MSG_BAND, and both a control part and data are not specified, no message is sent and a value of 0 (zero) is returned. If you set the flags parameter to 0 (zero), putpmsg() fails.

Unless the message is a high priority one, the putmsg() function generally blocks if the Stream write queue is full. This is because of internal flow control conditions. The putmsg() function does not block on this condition for high priority messages. However, for other messages, if the O_NDELAY or O_NONBLOCK flag is set for the write() operation, the putmsg() function will not block when the write queue is full. Instead, it fails.

In addition, unless the system runs out of internal resources, the putmsg() function will block while waiting for the availability of message blocks in the Stream. In this instance, neither the message priority nor the assertion of the O_NDELAY or O_NONBLOCK flag matter. Partial messages are not sent.

[Digital]  Current industry standards do not define the O_NDELAY flag. It is included in the preceding paragraphs for System V compatibility.  

NOTES

[Digital]  When compiled in the X/Open UNIX environment, calls to the putmsg() and putpmsg() functions are internally renamed by prepending _E to the function name. When you are debugging a module that includes the putmsg() or putpmsg() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Eputmsg to refer to the putmsg() call, and _Eputpmsg to refer to the putpmsg() call. See standards(5) for further information.  

RETURN VALUES

Upon successful completion, the putmsg() functions return a value of 0 (zero). Otherwise, they return a value of -1 and errno is set to indicate an error.  

ERRORS

The putmsg() function fails if the Stream head has processed a STREAM error message before either of these functions is called. In this instance, the STREAMS error message contains the value of the returned error.

In addition, if any of the following conditions occurs, the putmsg() function sets errno to the corresponding value. For a non-priority message, the O_NDELAY or the O_NONBLOCK flag is set, and the Stream write queue is determined to be full because of the internal flow control conditions.

[Digital]  Current industry standards do not define the O_NDELAY flag. It is included in the preceding paragraphs for System V compatibility.
The system could not allocate buffers for the message to be created. The fd parameter is not invalid for writing. The putmsg() function was interrupted by a signal that was caught. An undefined message was specified in the flags parameter.
For the putmsg() function, the flags parameter is RS_HIPRI or MSG_HIPRI, and the ctlbuf len parameter is less than 0 (zero).
For the putpmsg() function, the flags parameter is MSG_HIPRI and the ctlbuf len parameter is less than 0 (zero)
[Digital]   For the putpmsg() function, the flags parameter is MSG_HIPRI and the band parameter is not 0 (zero); or the flags parameter is MSG_BAND and the band parameter is greater than the system minimum.
The Stream specified by the fd parameter is linked under a multiplexor. The system could not allocate buffers for the message that was to be created because of insufficient Streams memory resources. A Stream is not associated with the fd parameter. The other end of a Streams-based piped referred to by the fd parameter is closed. A SIGPIPE signal is generated for the calling process. A hangup condition for the specified Stream was generated downstream. The size of the control part of a message is larger than the maximum configured size of the message's control part; or the data part of a message is larger than the maximum configured size of the message's data part; or the data part size of the message does not conform to the range indicated by the maximum and minimum packet sizes of the topmost Stream module.
 

RELATED INFORMATION

Functions: getmsg(2), poll(2), read(2), write(2)

Interfaces: streamio(7)

Standards: standards(5) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:16 GMT, October 02, 2010