'\" te
.\"  Copyright 1989 AT&T
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ESBALLOC 9F "Jan 16, 2006"
.SH NAME
esballoc, desballoc \- allocate a message block using a caller-supplied buffer
.SH SYNOPSIS
.LP
.nf
#include <sys/stream.h>



\fBmblk_t *\fR\fBesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
     \fBfrtn_t *\fR\fIfr_rtnp\fR);
.fi

.LP
.nf
\fBmblk_t *\fR\fBdesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
     \fBfrtn_t *\fR\fIfr_rtnp\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
\fBesballoc()\fR: Architecture independent level 1 (DDI/DKI)
.sp
.LP
\fBdesballoc()\fR: Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIbase\fR\fR
.ad
.RS 11n
Address of caller-supplied data buffer.
.RE

.sp
.ne 2
.na
\fB\fIsize\fR\fR
.ad
.RS 11n
Number of bytes in data buffer.
.RE

.sp
.ne 2
.na
\fB\fIpri\fR\fR
.ad
.RS 11n
Priority of the request (no longer used).
.RE

.sp
.ne 2
.na
\fB\fIfr_rtnp\fR\fR
.ad
.RS 11n
Free routine data structure.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBesballoc()\fR and \fBdesballoc()\fR functions operate identically to
\fBallocb\fR(9F), except that the data buffer to associate with the message is
specified by the caller. The allocated message will have both the \fBb_wptr\fR
and \fBb_rptr\fR set to the supplied data buffer starting at \fIbase\fR. Only
the buffer itself can be specified by the caller. The message block and data
block header are allocated as if by \fBallocb\fR(9F).
.sp
.LP
When \fBfreeb\fR(9F) is called to free the message, the driver's
message-freeing routine, referenced through the \fBfree_rtn\fR(9S) structure,
is called with appropriate arguments to free the data buffer.
.sp
.LP
The \fBfree_rtn\fR(9S) structure includes the following members:
.sp
.in +2
.nf
void (*free_func)();     /* caller's freeing routine */
caddr_t free_arg;        /* argument to free_func() */
.fi
.in -2

.sp
.LP
Instead of requiring a specific number of arguments, the \fBfree_arg\fR field
is defined of type \fBcaddr_t\fR. This way, the driver can pass a pointer to a
structure if more than one argument is needed.
.sp
.LP
If \fBesballoc()\fR was used, then \fBfree_func\fR will be called
asynchronously at some point after the message is no longer referenced. If
\fBdesballoc()\fR was used, then \fBfree_func\fR will be called synchronously
by the thread releasing the final reference. See \fBfreeb\fR(9F).
.sp
.LP
The \fBfree_func\fR 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 \fBdesballoc()\fR are freed in the
context of the caller, \fBfree_func\fR must not call another module's \fBput\fR
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, \fBfree_func\fR routines specified using
\fBdesballoc\fR may run in interrupt context and thus must only use
synchronization primitives that include an interrupt priority returned from
\fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). If any of
these restrictions are not followed, the possibility of lock recursion or
deadlock exists.
.SH RETURN VALUES
.sp
.LP
On success, a pointer to the newly allocated message block is returned. On
failure, \fBNULL\fR is returned.
.SH CONTEXT
.sp
.LP
The \fBesballoc()\fR and \fBdesballoc()\fR functions can be called from user,
interrupt, or kernel context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBallocb\fR(9F), \fBddi_intr_get_pri\fR(9F),
\fBddi_intr_get_softint_pri\fR(9F), \fBfreeb\fR(9F), \fBdatab\fR(9S),
\fBfree_rtn\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fISTREAMS Programming Guide\fR