merror(9f) [sunos man page]

merror(9F)						   Kernel Functions for Drivers 						merror(9F)

NAME

       merror - Send an M_ERROR message upstream

SYNOPSIS

       #include <sys/stream.h>
       #include <sys/strsun.h>

       void merror(queue_t *wq, mblk_t *mp, int error);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

PARAMETERS

       wq	       Write queue associated with the read queue to send the M_ERROR on.

       mp	       Optionally, a STREAMS message to convert to an M_ERROR.

       error	       Error code to include in the M_ERROR message.

DESCRIPTION

       The merror() function constructs an M_ERROR message, and sends the resulting message upstream.

       If  mp  is NULL, merror() allocates a one-byte M_ERROR message. If mp is non-NULL, merror() attempts to convert the passed-in message to an
       M_ERROR. However, if the passed-in message has more than one reference (see dupmsg(9F)), or if it is of zero length, it is freed and a  new
       message is allocated.

       If  the	allocation  or	conversion  fails, merror() silently fails. Otherwise, the resulting one-byte data block is assigned the specified
       error code and sent upstream.

RETURN VALUES

       None.

CONTEXT

       This function can be called from user, kernel or interrupt context.

NOTES

       Callers must not hold any locks across an merror() that can be acquired as part of put(9E) processing.

SEE ALSO

       put(9E), dupmsg(9F)

       STREAMS Programming Guide

SunOS 5.10							    9 June 2004 							merror(9F)

allocb(9F)						   Kernel Functions for Drivers 						allocb(9F)

NAME

       allocb - allocate a message block

SYNOPSIS

       #include <sys/stream.h>

       mblk_t *allocb(size_t size, uint_t pri);

INTERFACE LEVEL

       Architecture independent level 1 (DDI/DKI).

DESCRIPTION

       The allocb() function tries to allocate a STREAMS message block.  Buffer allocation fails only when the system is out of memory. If no buf-
       fer is available, the bufcall(9F) function can help a module recover from an allocation failure.

       A STREAMS message block is composed of three structures. The first structure is a message block (mblk_t). See msgb(9S). The  mblk_t  struc-
       ture  points to a data block structure (dblk_t). See datab(9S). Together these two structures describe the message type (if applicable) and
       the size and location of the third structure, the data buffer. The data buffer contains the data for this message block. The allocated data
       buffer is at least double-word aligned, so it can hold any C data structure.

       The fields in the mblk_t structure are initialized as follows:

       b_cont	  set to  NULL

       b_rptr	  points to the beginning of the data buffer

       b_wptr	  points to the beginning of the data buffer

       b_datap	  points to the dblk_t structure

       The fields in the dblk_t structure are initialized as follows:

       db_base	  points to the first byte of the data buffer

       db_lim	  points to the last byte + 1 of the buffer

       db_type	  set to M_DATA

       The following figure identifies the data structure members that are affected when a message block is allocated.

       Printed copy or docs.sun.com shows a figure that identifies the data structure members that are affected when a message block is allocated

PARAMETERS

       size    The number of bytes in the message block.

       pri     Priority of the request (no longer used).

RETURN VALUES

       Upon success, allocb() returns a pointer to the allocated message block of type M_DATA. On failure, allocb() returns a NULL pointer.

CONTEXT

       The allocb() function can be called from user, interrupt, or kernel context.

EXAMPLES

       Example 1 allocb() Code Sample

       Given a pointer to a queue (q) and an error number (err), the  send_error() routine sends an  M_ERROR type message to the stream head.

       If  a  message  cannot  be  allocated,  NULL  is returned, indicating an allocation failure (line 8). Otherwise, the message type is set to
       M_ERROR (line 10). Line 11 increments the write pointer	(bp->b_wptr) by the size (one byte) of the data in the message.

       A message must be sent up the read side of the stream to arrive at the stream head. To determine whether  q points to a read queue or to  a
       write  queue, the q->q_flag member is tested to see if QREADR is set (line 13). If it is not set, q points to a write queue, and in line 14
       the RD(9F) function is used to find the corresponding read queue. In line 15,  the  putnext(9F)	function  is  used  to	send  the  message
       upstream, returning 1 if successful.

	 1  send_error(q,err)
	 2    queue_t *q;
	 3    unsigned char err;
	 4  {
	 5    mblk_t *bp;
	 6
	 7    if ((bp = allocb(1, BPRI_HI)) == NULL) /* allocate msg. block */
	 8	   return(0);
	 9
	 10    bp->b_datap->db_type = M_ERROR;	  /* set msg type to M_ERROR */
	 11    *bp->b_wptr++ = err;		  /* increment write pointer */
	 12
	 13    if (!(q->q_flag & QREADR))	  /* if not read queue	   */
	 14	    q = RD(q);			  /*	get read queue	   */
	 15    putnext(q,bp);			  /* send message upstream */
	 16    return(1);
	 17  }

SEE ALSO

       RD(9F), bufcall(9F), esballoc(9F), esbbcall(9F), putnext(9F), testb(9F), datab(9S), msgb(9S)

       Writing Device Drivers

       STREAMS Programming Guide

NOTES

       The pri argument is no longer used, but is retained for compatibility with existing drivers.

SunOS 5.11							    16 Jan 2006 							allocb(9F)