Kernel Functions for Drivers                         esballoc(9F)



NAME
     esballoc, desballoc -  allocate  a  message  block  using  a
     caller-supplied buffer

SYNOPSIS
     #include 



     mblkt *esballoc(uchart *base, sizet size, uintt pri,
          frtnt *frrtnp);


     mblkt *desballoc(uchart *base, sizet size, uintt pri,
          frtnt *frrtnp);


INTERFACE LEVEL
     esballoc(): Architecture independent level 1 (DI/DKI)


     desballoc(): Solaris DI specific (Solaris DI)

PARAMETERS
     base       Address of caller-supplied data buffer.


     size       Number of bytes in data buffer.


     pri        Priority of the request (no longer used).


     frrtnp    Free routine data structure.


DESCRIPTION
     The esballoc() and desballoc() functions operate identically
     to allocb(9F), except that the data buffer to associate with
     the message is specified by the caller. The  allocated  mes-
     sage  will  have  both the bwptr and brptr set to the sup-
     plied data buffer starting at base. Only the  buffer  itself
     can  be  specified by the caller. The message block and data
     block header are allocated as if by allocb(9F).


     When freeb(9F) is called to free the message,  the  driver's
     message-freeing routine, referenced through the freertn(9S)
     structure, is called with appropriate arguments to free  the
     data buffer.





SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                         esballoc(9F)



     The freertn(9S) structure includes the following members:

       void (*freefunc)();     /* caller's freeing routine */
       caddrt freearg;        /* argument to freefunc() */



     Instead of requiring a specific  number  of  arguments,  the
     freearg  field  is  defined  of type caddrt. This way, the
     driver can pass a pointer to a structure if  more  than  one
     argument is needed.


     If esballoc() was used, then freefunc will be called  asyn-
     chronously  at  some  point  after  the message is no longer
     referenced. If desballoc() was used, then freefunc will  be
     called  synchronously  by  the  thread  releasing  the final
     reference. See freeb(9F).


     The freefunc routine must not sleep, and  must  not  access
     any  dynamically  allocated  data  structures  that could be
     freed before or during its execution. In  addition,  because
     messages allocated with desballoc() are freed in the context
     of the caller, freefunc must not call another module's  put
     procedure, or attempt to acquire a private module lock which
     might be held by another thread across a call to  a  STREAMS
     utility  routine  that  could free a message block. Finally,
     freefunc routines specified  using  desballoc  may  run  in
     interrupt  context  and  thus  must only use synchronization
     primitives that include an interrupt priority returned  from
     ddiintrgetpri(9F) or ddiintrgetsoftintpri(9F). If any
     of these restrictions are not followed, the  possibility  of
     lock recursion or deadlock exists.

RETURN VALUES
     On success, a pointer to the newly allocated  message  block
     is returned. On failure, NUL is returned.

CONTEXT
     The esballoc() and desballoc() functions can be called  from
     user, interrupt, or kernel context.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:









SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                         esballoc(9F)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Committed                   
    


SEE ALSO
     allocb(9F),                            ddiintrgetpri(9F),
     ddiintrgetsoftintpri(9F),      freeb(9F),     datab(9S),
     freertn(9S)


     Writing Device Drivers


     STREAMS Programming Guide






































SunOS 5.11          Last change: 16 Jan 2006                    3