Manual Pages for UNIX Operating System command usage for man putnextctl

Kernel Functions for Drivers                       putnextctl(9F)



NAME
     putnextctl - send a control message to a queue

SYNOPSIS
     #include 



     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 allo-
     cated and initialized messages.


     A call to putnextctl(q,type)  is  an  atomic  equivalent  of
     putctl(q->q_next,type). The STREAMS framework provides what-
     ever mutual exclusion is  necessary  to  insure  that  dere-
     ferencing  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  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 send_ctl routine is used to pass control messages  down-
     stream.  M_BREAK  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 M_DELAY 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,  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 ALSO
     put(9E),     cmn_err(9F),      datamsg(9F),      putctl(9F),
     putnextctl1(9F)


     Writing Device Drivers


     STREAMS Programming Guide















SunOS 5.11          Last change: 16 Jan 2006                    2