putnextctl(9F) Kernel Functions for Drivers putnextctl(9F)NAMEputnextctl - send a control message to a queue
SYNOPSIS
#include <sys/stream.h>
int putnextctl(queue_t *q, int type);
INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI).
PARAMETERS
q Queue to which the message is to be sent.
type Message type (must be control, not data type).
DESCRIPTION
The putnextctl() function tests the type argument to make sure a data
type has not been specified, and then attempts to allocate a message
block. putnextctl() fails if type is M_DATA, M_PROTO, or M_PCPROTO, or
if a message block cannot be allocated. If successful, putnextctl()
calls the put(9E) routine of the queue pointed to by q with the newly
allocated and initialized messages.
A call to putnextctl(q,type) is an atomic equivalent of
putctl(q->q_next,type). The STREAMS framework provides whatever mutual
exclusion is necessary to insure that dereferencing q through its
q_next field and then invoking putctl(9F) proceeds without interference
from other threads.
The putnextctl() function should always be used in preference to
putctl(9F)RETURN VALUES
On success, 1 is returned. If type is a data type, or if a message
block cannot be allocated, 0 is returned.
CONTEXT
The putnextctl() function can be user, interrupt, or kernel context.
EXAMPLES
The send_ctl routine is used to pass control messages downstream.
M_BREAK messages are handled with putnextctl() (line 8). put‐
nextctl1(9F) (line 13) is used for M_DELAY messages, so that parm can
be used to specify the length of the delay. In either case, if a mes‐
sage block cannot be allocated a variable recording the number of
allocation failures is incremented (lines 9, 14). If an invalid mes‐
sage type is detected, cmn_err(9F) panics the system (line 18).
1 void
2 send_ctl(queue_t *wrq, uchar_t type, uchar_t parm)
3 {
4 extern int num_alloc_fail;
5
6 switch (type) {
7 case M_BREAK:
8 if (!putnextctl(wrq, M_BREAK))
9 num_alloc_fail++;
10 break;
11
12 case M_DELAY:
13 if (!putnextctl1(wrq, M_DELAY, parm))
14 num_alloc_fail++;
15 break;
16
17 default:
18 cmn_err(CE_PANIC, "send_ctl: bad message type passed");
19 break;
20 }
21 }
SEE ALSOput(9E), cmn_err(9F), datamsg(9F), putctl(9F), putnextctl1(9F)
Writing Device Drivers
STREAMS Programming Guide
SunOS 5.10 16 Jan 2006 putnextctl(9F)
