SVR5 and SCO OpenServer 5

putctl(D3str)

putctl -- send a control message to a queue

Synopsis

   #include <sys/stream.h>
   #include <sys/ddi.h>
   
   int putctl(queue_t *q, int type);

Description

putctl tests the type argument to make sure a data type has not been specified, and then attempts to allocate a message block. putctl fails if type is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If successful, putctl calls the put(D2str) routine of the queue pointed to by q, passing it the allocated message.

Arguments

q: Pointer to the queue to which the message is to be sent.
type: Message type (must be a control type).

Return values

On success, 1 is returned. Otherwise, if type is a data type, or if a message block cannot be allocated, 0 is returned.

Usage

In multithreaded DDI drivers, the q argument may not reference q_next. For example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI). putnextctl(q, type) is provided as a multiprocessor-safe equivalent to the common call putctl(q->q_next, type), which is no longer allowed.

Context

Base or Interrupt.

Synchronization constraints

Does not block.

Driver-defined basic locks, read/write locks, and sleep locks may not be held across calls to this function.

The caller cannot have the stream frozen (see freezestr(D3str)) when calling this function.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

References

put(D2str), put(D3str), putctl1(D3str), putnextctl(D3str), putnextctl1(D3str)

Examples

The send_ctl routine is used to pass control messages downstream. M_BREAK messages are handled with putctl (line 9). putctl1 (line 11) is used for M_DELAY messages, so that param can be used to specify the length of the delay. If an invalid message type is detected, send_ctl returns 0, indicating failure (line 13).

    1  int
    2  send_ctl(wrq, type, param)
    3	queue_t *wrq;
    4	uchar_t type;
    5	uchar_t param;
    6  {

    7	switch (type) {
    8	case M_BREAK:
    9		return(putctl(wrq->q_next, M_BREAK));

   10	case M_DELAY:
   11		return(putctl1(wrq->q_next, M_DELAY, param));

   12	default:
   13		return(0);
   14	}
   15  }