Kernel Functions for Drivers                       putnextctl(9F)



NAME
     putnextctl - send a control message to a queue

SYNOPSIS
     #include 



     int putnextctl(queuet *q, int type);


INTERFACE LEVEL
     Architecture independent level 1 (DI/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
     MDATA,  MPROTO, or MPCPROTO, 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 allo-
     cated and initialized messages.


     A call to putnextctl(q,type)  is  an  atomic  equivalent  of
     putctl(q->qnext,type). The STREAMS framework provides what-
     ever mutual exclusion is  necessary  to  insure  that  dere-
     ferencing  q  through  its  qnext  field  and then invoking
     putctl(9F) proceeds without interference from other threads.


     The putnextctl() function should always be used  in  prefer-
     ence 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 sendctl routine is used to pass control messages  down-
     stream.  MBREAK  messages  are  handled  with  putnextctl()



SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                       putnextctl(9F)



     (line 8). putnextctl1(9F) (line 13) is used for MDELAY mes-
     sages,   so  that  parm can be used to specify the length of
     the delay. In either case, if  a  message  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,  cmnerr(9F) panics the system (line
     18).

       1 void
        2 sendctl(queuet *wrq, uchart type, uchart parm)
        3 {
        4           extern int numallocfail;
        5
        6           switch (type) {
        7         case MBREAK:
        8                if (!putnextctl(wrq, MBREAK))
        9                           numallocfail];
       10                  break;
       11
       12           case MDELAY:
       13                if (!putnextctl1(wrq, MDELAY, parm))
       14                           numallocfail];
       15                break;
       16
       17         default:
       18                cmnerr(CEPANIC, "sendctl: bad message type passed");
       19                  break;
       20           }
       21  }


SEE ALSO
     put(9E),     cmnerr(9F),      datamsg(9F),      putctl(9F),
     putnextctl1(9F)


     Writing Device Drivers


     STREAMS Programming Guide















SunOS 5.11          Last change: 16 Jan 2006                    2