esballoc(9f)

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

NAME

6       esballoc,  desballoc - allocate a message block using a caller-supplied
7       buffer
8

SYNOPSIS

10       #include <sys/stream.h>
11
12
13
14       mblk_t *esballoc(uchar_t *base, size_t size, uint_t pri,
15            frtn_t *fr_rtnp);
16
17
18       mblk_t *desballoc(uchar_t *base, size_t size, uint_t pri,
19            frtn_t *fr_rtnp);
20
21

INTERFACE LEVEL

23       esballoc(): Architecture independent level 1 (DDI/DKI)
24
25
26       desballoc(): Solaris DDI specific (Solaris DDI)
27

PARAMETERS

29       base       Address of caller-supplied data buffer.
30
31
32       size       Number of bytes in data buffer.
33
34
35       pri        Priority of the request (no longer used).
36
37
38       fr_rtnp    Free routine data structure.
39
40

DESCRIPTION

42       The  esballoc()  and  desballoc()  functions  operate  identically   to
43       allocb(9F),  except  that the data buffer to associate with the message
44       is specified by the caller. The allocated message will  have  both  the
45       b_wptr  and  b_rptr  set  to the supplied data buffer starting at base.
46       Only the buffer itself can be specified  by  the  caller.  The  message
47       block and data block header are allocated as if by allocb(9F).
48
49
50       When  freeb(9F)  is  called  to free the message, the driver's message-
51       freeing routine, referenced  through  the  free_rtn(9S)  structure,  is
52       called with appropriate arguments to free the data buffer.
53
54
55       The free_rtn(9S) structure includes the following members:
56
57         void (*free_func)();     /* caller's freeing routine */
58         caddr_t free_arg;        /* argument to free_func() */
59
60
61
62       Instead of requiring a specific number of arguments, the free_arg field
63       is defined of type caddr_t. This way, the driver can pass a pointer  to
64       a structure if more than one argument is needed.
65
66
67       If esballoc() was used, then free_func will be called asynchronously at
68       some point after the message is no longer  referenced.  If  desballoc()
69       was  used,  then  free_func  will be called synchronously by the thread
70       releasing the final reference. See freeb(9F).
71
72
73       The free_func routine must not sleep, and must not access  any  dynami‐
74       cally  allocated  data  structures that could be freed before or during
75       its execution. In addition, because messages allocated with desballoc()
76       are freed in the context of the caller, free_func must not call another
77       module's put procedure, or attempt to acquire  a  private  module  lock
78       which  might be held by another thread across a call to a STREAMS util‐
79       ity routine that could free a message block.  Finally,  free_func  rou‐
80       tines  specified  using desballoc may run in interrupt context and thus
81       must only use synchronization primitives that include an interrupt pri‐
82       ority   returned   from   ddi_intr_get_pri(9F)   or  ddi_intr_get_soft‐
83       int_pri(9F). If any of these restrictions are not followed, the  possi‐
84       bility of lock recursion or deadlock exists.
85

RETURN VALUES

87       On success, a pointer to the newly allocated message block is returned.
88       On failure, NULL is returned.
89

CONTEXT

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

ATTRIBUTES

95       See attributes(5) for descriptions of the following attributes:
96
97
98
99
100       ┌─────────────────────────────┬─────────────────────────────┐
101       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
102       ├─────────────────────────────┼─────────────────────────────┤
103       │Interface Stability          │Committed                    │
104       └─────────────────────────────┴─────────────────────────────┘
105