[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Communications Technical Reference, 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.

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.

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 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.

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:

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.
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.

Implementation Specifics

This system call is part of STREAMS Kernel Extensions.

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 Version 4.3 Communications Programming Concepts.


[ Previous | Next | Contents | Glossary | Home | Search ]