putnextctl(9f)

1putnextctl(9F)           Kernel Functions for Drivers           putnextctl(9F)
2
3
4

NAME

6       putnextctl - send a control message to a queue
7

SYNOPSIS

9       #include <sys/stream.h>
10
11
12
13       int putnextctl(queue_t *q, int type);
14
15

INTERFACE LEVEL

17       Architecture independent level 1 (DDI/DKI).
18

PARAMETERS

20       q       Queue to which the message is to be sent.
21
22
23       type    Message type (must be control, not data type).
24
25

DESCRIPTION

27       The  putnextctl()  function tests the type argument to make sure a data
28       type has not been specified, and then attempts to  allocate  a  message
29       block.  putnextctl() fails if type is M_DATA, M_PROTO, or M_PCPROTO, or
30       if a message block cannot be  allocated.  If  successful,  putnextctl()
31       calls  the  put(9E) routine of the queue pointed to by q with the newly
32       allocated and initialized messages.
33
34
35       A   call   to   putnextctl(q,type)   is   an   atomic   equivalent   of
36       putctl(q->q_next,type).  The STREAMS framework provides whatever mutual
37       exclusion is necessary to  insure  that  dereferencing  q  through  its
38       q_next field and then invoking putctl(9F) proceeds without interference
39       from other threads.
40
41
42       The putnextctl() function  should  always  be  used  in  preference  to
43       putctl(9F)
44

RETURN VALUES

46       On  success,  1  is  returned.  If type is a data type, or if a message
47       block cannot be allocated, 0 is returned.
48

CONTEXT

50       The putnextctl() function can be user, interrupt, or kernel context.
51

EXAMPLES

53       The send_ctl routine is  used  to  pass  control  messages  downstream.
54       M_BREAK   messages  are  handled  with   putnextctl()  (line  8).  put‐
55       nextctl1(9F) (line 13) is used for M_DELAY messages,  so that  parm can
56       be  used  to specify the length of the delay. In either case, if a mes‐
57       sage block cannot be allocated  a  variable  recording  the  number  of
58       allocation  failures   is incremented (lines 9, 14). If an invalid mes‐
59       sage type is detected,  cmn_err(9F) panics the system (line 18).
60
61         1 void
62          2 send_ctl(queue_t *wrq, uchar_t type, uchar_t parm)
63          3 {
64          4           extern int num_alloc_fail;
65          5
66          6           switch (type) {
67          7         case M_BREAK:
68          8                if (!putnextctl(wrq, M_BREAK))
69          9                           num_alloc_fail++;
70         10                  break;
71         11
72         12           case M_DELAY:
73         13                if (!putnextctl1(wrq, M_DELAY, parm))
74         14                           num_alloc_fail++;
75         15                break;
76         16
77         17         default:
78         18                cmn_err(CE_PANIC, "send_ctl: bad message type passed");
79         19                  break;
80         20           }
81         21  }
82
83