'\"macro stdmacro
.if n .pH ddi_dki.esballoc @(#)esballoc	40.6 of 12/19/89
.\" Copyright 1989 AT&T
.de IX
.ie '\\n(.z'' .tm .Index: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9	\\n%
.el \\!.IX \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.nr X
.if \nX=0 .ds x} esballoc D3DK "STREAMS" "DDI/DKI" "\&"
.if \nX=1 .ds x} esballoc D3DK "STREAMS" "DDI/DKI"
.if \nX=2 .ds x} esballoc D3DK "" "\&"
.if \nX=3 .ds x} esballoc "" "" "\&"
.TH \*(x}
.IX "\f4esballoc\fP(D3DK)"
.SH NAME
\f4esballoc\f1 \- allocate a message block using a shared buffer
.SH SYNOPSIS
.nf
.na
\f4#include <sys/stream.h>
.sp 0.5
mblk_t *esballoc(unsigned char *\f2base, \f4int \f2size, \f4int \f2pri,
	\f4frtn_t *\f2fr_rtnp\f4);\f1
.ad
.fi
.SH ARGUMENTS
.RS 0n 10
.IP "\f2base\f1" 10n
Address of user supplied data buffer.
.IP "\f2size\f1" 10n
Number of bytes in data buffer.
.IP "\f2pri\f1" 10n
Priority of allocation request (to be used by \f4allocb\f1(D3DK) function,
called by \f4esballoc\f1).
.IP "\f2fr_rtnp\f1" 10n
Free routine data structure.
.RE
.SH DESCRIPTION
\f4esballoc\f1 creates a STREAMS message and attaches a user-supplied
data buffer in place of a STREAMS data buffer.
It calls \f4allocb\f1(D3DK) to get a message and data block header only.
The user-supplied data buffer, pointed to by \f2base\f1, is used as the
data buffer for the message.
.P
The \f4free_rtn\f1 structure is referenced by the \f4dp_freep\f1
member of the \f4datab\f1 structure.
When \f4freeb\f1(D3DK) is called to free the message, the driver's message
freeing routine (referenced through the \f4free_rtn\f1 structure) is
called, with arguments, to free the data buffer.
.P
The \f4free_rtn\f1 structure has the following declaration:
.P
.RS
.ft 4
.nf
struct free_rtn {
	void (*free_func)(); /* user's freeing routine */
	char *free_arg;      /* arguments to free_func() */
}
typedef struct free_rtn frtn_t;
.fi
.ft 1
.RE
.P
Instead of requiring a specific number of arguments, the \f4free_arg\f1
field is defined of type \f4char *\f1.
This way, the driver can pass a pointer to a structure if more than one
argument is needed.
.P
\f3NOTE:\f1
The \f4free_func\f1 function must be defined in kernel
space, should be declared \f4void\f1 and accept one argument.  It has
no user context and must not sleep.
.SH RETURN VALUE
On success, a pointer to the newly allocated message block is returned.
On failure, \f4NULL\f1 is returned.
.SH LEVEL
Base or Interrupt
.SH SEE ALSO
.na
\f4allocb\f1(D3DK),
\f4freeb\f1(D3DK),
\f4datab\f1(D4DK),
\f4free_rtn\f1(D4DK)
.ad
