[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Communications, Volume 2


putq Utility

Purpose

Puts a message on a queue.

Syntax


int
putq(q, bp)
register queue_t * q;
register mblk_t * bp;

Description

The putq utility puts the message pointed to by the bp parameter on the message queue pointed to by the q parameter, and then enables that queue. The putq utility queues messages based on message-queuing priority.

The priority classes are:

type >= QPCTL High-priority
type < QPCTL && band > 0 Priority band
type < QPCTL && band == 0 Normal

When a high-priority message is queued, the putq utility always enables the queue. For a priority-band message, the putq utility is allowed to enable the queue (the QNOENAB flag is not set). Otherwise, the QWANTR flag is set, indicating that the service procedure is ready to read the queue. When an ordinary message is queued, the putq utility enables the queue if the following condition is set and if enabling is not inhibited by the noenable utility: the module has just been pushed, or else no message was queued on the last getq call and no message has been queued since.

The putq utility looks only at the priority band in the first message block of a message. If a high-priority message is passed to the putq utility with a nonzero b_band field value, the b_band field is reset to 0 before the message is placed on the queue. If the message passed to the putq utility has a b_band field value greater than the number of qband structures associated with the queue, the putq utility tries to allocate a new qband structure for each band up to and including the band of the message.

The putq utility should be used in the put procedure for the same queue in which the message is queued. A module should not call the putq utility directly in order to pass messages to a neighboring module. Instead, the putq utility itself can be used as the value of the qi_putp field in the put procedure for either or both of the module qinit structures. Doing so effectively bypasses any put-procedure processing and uses only the module service procedures.

Note: The service procedure must never put a priority message back on its own queue, as this would result in an infinite loop.

Parameters


q Specifies the queue on which to place the message.
bp Specifies the message to put on the queue.

Return Values

On successful completion, the putq utility returns a value of 1. Otherwise, it returns a value of 0.

Implementation Specifics

This utility is part of STREAMS Kernel Extensions.

Related Information

The getq utility.

List of Streams Programming References and Understanding STREAMS Messages in AIX 5L Version 5.1 Communications Programming Concepts.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]