share/man/man3dlpi/dlpi_enabnotify.3dlpi

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DLPI_ENABNOTIFY 3DLPI "Mar 10, 2009"
   7 .SH NAME
   8 dlpi_enabnotify \- enable DLPI notification
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... -\fBldlpi\fR [ \fIlibrary\fR... ]
  13 #include <libdlpi.h>
  14
  15 \fBint\fR \fBdlpi_enabnotify\fR(\fBdlpi_handle_t\fR \fIdh\fR, \fBuint_t\fR \fInotes\fR,
  16      \fBdlpi_notifyfunc_t *\fR\fIfuncp\fR, \fBvoid *\fR\fIarg\fR, \fBdlpi_notifyid_t *\fR\fIid\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBtypedef void\fR \fBdlpi_notifyfunc_t\fR(\fBdlpi_handle_t\fR,
  22      \fBdlpi_notifyinfo_t *\fR, \fBvoid *\fR);
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBdlpi_enabnotify()\fR function enables a notification callback for the
  29 set of events specified in \fInotes\fR, which must be one or more (by a logical
  30 OR operation) of the DLPI notifications documented in \fBdlpi\fR(7P).   The
  31 callback function \fIfuncp\fR is registered with the DLPI handle \fIdh\fR and
  32 is invoked when \fIdh\fR receives notification for any of the specified event
  33 types. Upon success, \fIid\fR contains the identifier associated with the
  34 registration.
  35 .sp
  36 .LP
  37 Multiple event types can be registered for a callback function on the DLPI
  38 handle \fIdh\fR. Similarly, the same event type can be registered multiple
  39 times on the same handle.
  40 .sp
  41 .LP
  42 Once a callback has been registered, \fBlibdlpi\fR will check for notification
  43 events on the DLPI handle \fIdh\fR, when exchanging DLPI messages with the
  44 underlying DLPI link instance. The \fBdlpi_recv\fR(3DLPI) function will always
  45 check for notification events, but other \fBlibdlpi\fR operations may also lead
  46 to an event callback being invoked. Although there may be no expected data
  47 messages to be received, \fBdlpi_recv()\fR can be called, as shown below, with
  48 a null buffer to force a check for pending events on the underlying DLPI link
  49 instance.
  50 .sp
  51 .in +2
  52 .nf
  53 dlpi_recv(dh, NULL, NULL, NULL, NULL, 0, NULL);
  54 .fi
  55 .in -2
  56
  57 .sp
  58 .LP
  59 When a notification event of interest occurs, the callback function is invoked
  60 with the arguments \fIarg\fR, originally passed to
  61 \fBdlpi_disabnotify\fR(3DLPI), and \fIinfop\fR, whose members are described
  62 below.
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBuint_t\fR \fIdni_note\fR\fR
  67 .ad
  68 .RS 27n
  69 Notification event type.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBuint_t\fR \fIdni_speed\fR\fR
  76 .ad
  77 .RS 27n
  78 Current speed, in kilobits per second, of the DLPI link. Valid only for
  79 \fBDL_NOTE_SPEED\fR.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBuint_t\fR \fIdni_size\fR\fR
  86 .ad
  87 .RS 27n
  88 Current maximum message size, in bytes, that the DLPI link is able to accept
  89 for transmission. Valid only for \fBDL_NOTE_SDU_SIZE\fR.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBuchar_t\fR \fIdni_physaddrlen\fR\fR
  96 .ad
  97 .RS 27n
  98 Link-layer physical address length, in bytes. Valid only for
  99 \fBDL_NOTE_PHYS_ADDR\fR.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBuchar_t\fR \fIdni_physaddr\fR[]\fR
 106 .ad
 107 .RS 27n
 108 Link-layer physical address of DLPI link.  Valid only for
 109 \fBDL_NOTE_PHYS_ADDR\fR.
 110 .RE
 111
 112 .sp
 113 .LP
 114 The \fBlibdlpi\fR library will allocate and free the \fBdlpi_notifyinfo_t\fR
 115 structure and the caller must not allocate the structure or perform any
 116 operations that require its size to be known.
 117 .sp
 118 .LP
 119 The callback is not allowed to block.  This precludes calling
 120 \fBdlpi_enabnotify()\fR from a callback, but non-blocking \fBlibdlpi\fR
 121 functions, including \fBdlpi_disabnotify()\fR, can be called.
 122 .SH RETURN VALUES
 123 .sp
 124 .LP
 125 Upon success, \fBDLPI_SUCCESS\fR is returned. If  \fBDL_SYSERR\fR  is returned,
 126 \fBerrno\fR  contains  the  specific  UNIX system error value. Otherwise, a
 127 DLPI error value defined in \fB<sys/dlpi.h>\fR or an error value listed in the
 128 following section is returned.
 129 .SH ERRORS
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBDLPI_EINHANDLE\fR\fR
 134 .ad
 135 .RS 21n
 136 A DLPI handle is invalid.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBDLPI_EINVAL\fR\fR
 143 .ad
 144 .RS 21n
 145 An argument is invalid.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBDLPI_ENOTEIDINVAL\fR\fR
 152 .ad
 153 .RS 21n
 154 The DLPI notification ID is invalid.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBDLPI_ENOTENOTSUP\fR\fR
 161 .ad
 162 .RS 21n
 163 The DLPI notification is not supported by the link.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBDLPI_ETIMEDOUT\fR\fR
 170 .ad
 171 .RS 21n
 172 The DLPI operation timed out.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBDLPI_FAILURE\fR\fR
 179 .ad
 180 .RS 21n
 181 The DLPI operation failed.
 182 .RE
 183
 184 .SH ATTRIBUTES
 185 .sp
 186 .LP
 187 See \fBattributes\fR(5) for descriptions of the following attributes:
 188 .sp
 189
 190 .sp
 191 .TS
 192 box;
 193 c | c
 194 l | l .
 195 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 196 _
 197 Interface Stability     Committed
 198 _
 199 MT-Level        Safe
 200 .TE
 201
 202 .SH SEE ALSO
 203 .sp
 204 .LP
 205 \fBdlpi_disabnotify\fR(3DLPI), \fBdlpi_recv\fR(3DLPI), \fBlibdlpi\fR(3LIB),
 206 \fBattributes\fR(5), \fBdlpi\fR(7P)