share/man/man9f/esballoc.9f

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH ESBALLOC 9F "Jan 16, 2006"
   8 .SH NAME
   9 esballoc, desballoc \- allocate a message block using a caller-supplied buffer
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/stream.h>
  14
  15
  16
  17 \fBmblk_t *\fR\fBesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
  18      \fBfrtn_t *\fR\fIfr_rtnp\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBmblk_t *\fR\fBdesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
  24      \fBfrtn_t *\fR\fIfr_rtnp\fR);
  25 .fi
  26
  27 .SH INTERFACE LEVEL
  28 .sp
  29 .LP
  30 \fBesballoc()\fR: Architecture independent level 1 (DDI/DKI)
  31 .sp
  32 .LP
  33 \fBdesballoc()\fR: Solaris DDI specific (Solaris DDI)
  34 .SH PARAMETERS
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIbase\fR\fR
  39 .ad
  40 .RS 11n
  41 Address of caller-supplied data buffer.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIsize\fR\fR
  48 .ad
  49 .RS 11n
  50 Number of bytes in data buffer.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIpri\fR\fR
  57 .ad
  58 .RS 11n
  59 Priority of the request (no longer used).
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIfr_rtnp\fR\fR
  66 .ad
  67 .RS 11n
  68 Free routine data structure.
  69 .RE
  70
  71 .SH DESCRIPTION
  72 .sp
  73 .LP
  74 The \fBesballoc()\fR and \fBdesballoc()\fR functions operate identically to
  75 \fBallocb\fR(9F), except that the data buffer to associate with the message is
  76 specified by the caller. The allocated message will have both the \fBb_wptr\fR
  77 and \fBb_rptr\fR set to the supplied data buffer starting at \fIbase\fR. Only
  78 the buffer itself can be specified by the caller. The message block and data
  79 block header are allocated as if by \fBallocb\fR(9F).
  80 .sp
  81 .LP
  82 When \fBfreeb\fR(9F) is called to free the message, the driver's
  83 message-freeing routine, referenced through the \fBfree_rtn\fR(9S) structure,
  84 is called with appropriate arguments to free the data buffer.
  85 .sp
  86 .LP
  87 The \fBfree_rtn\fR(9S) structure includes the following members:
  88 .sp
  89 .in +2
  90 .nf
  91 void (*free_func)();     /* caller's freeing routine */
  92 caddr_t free_arg;        /* argument to free_func() */
  93 .fi
  94 .in -2
  95
  96 .sp
  97 .LP
  98 Instead of requiring a specific number of arguments, the \fBfree_arg\fR field
  99 is defined of type \fBcaddr_t\fR. This way, the driver can pass a pointer to a
 100 structure if more than one argument is needed.
 101 .sp
 102 .LP
 103 If \fBesballoc()\fR was used, then \fBfree_func\fR will be called
 104 asynchronously at some point after the message is no longer referenced. If
 105 \fBdesballoc()\fR was used, then \fBfree_func\fR will be called synchronously
 106 by the thread releasing the final reference. See \fBfreeb\fR(9F).
 107 .sp
 108 .LP
 109 The \fBfree_func\fR routine must not sleep, and must not access any dynamically
 110 allocated data structures that could be freed before or during its execution.
 111 In addition, because messages allocated with \fBdesballoc()\fR are freed in the
 112 context of the caller, \fBfree_func\fR must not call another module's \fBput\fR
 113 procedure, or attempt to acquire a private module lock which might be held by
 114 another thread across a call to a STREAMS utility routine that could free a
 115 message block. Finally, \fBfree_func\fR routines specified using
 116 \fBdesballoc\fR may run in interrupt context and thus must only use
 117 synchronization primitives that include an interrupt priority returned from
 118 \fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). If any of
 119 these restrictions are not followed, the possibility of lock recursion or
 120 deadlock exists.
 121 .SH RETURN VALUES
 122 .sp
 123 .LP
 124 On success, a pointer to the newly allocated message block is returned. On
 125 failure, \fBNULL\fR is returned.
 126 .SH CONTEXT
 127 .sp
 128 .LP
 129 The \fBesballoc()\fR and \fBdesballoc()\fR functions can be called from user,
 130 interrupt, or kernel context.
 131 .SH ATTRIBUTES
 132 .sp
 133 .LP
 134 See \fBattributes\fR(5) for descriptions of the following attributes:
 135 .sp
 136
 137 .sp
 138 .TS
 139 box;
 140 c | c
 141 l | l .
 142 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 143 _
 144 Interface Stability     Committed
 145 .TE
 146
 147 .SH SEE ALSO
 148 .sp
 149 .LP
 150 \fBallocb\fR(9F), \fBddi_intr_get_pri\fR(9F),
 151 \fBddi_intr_get_softint_pri\fR(9F), \fBfreeb\fR(9F), \fBdatab\fR(9S),
 152 \fBfree_rtn\fR(9S)
 153 .sp
 154 .LP
 155 \fIWriting Device Drivers\fR
 156 .sp
 157 .LP
 158 \fISTREAMS Programming Guide\fR