share/man/man9f/net_hook_register.9f

   1 '\" te
   2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright (C) 2012, Joyent, 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 NET_HOOK_REGISTER 9F "Mar 5, 2012"
   8 .SH NAME
   9 net_hook_register \- add a hook to be called in event processing
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/neti.h>
  14
  15 \fBint\fR \fBnet_hook_register\fR(\fBnet_handle_t\fR \fIinfo\fR, \fBchar\fR *\fIevent\fR, \fBhook_t\fR *\fIhook\fR);
  16 .fi
  17
  18 .SH INTERFACE LEVEL
  19 .sp
  20 .LP
  21 Solaris DDI specific (Solaris DDI).
  22 .SH PARAMETERS
  23 .sp
  24 .ne 2
  25 .na
  26 \fB\fIinfo\fR\fR
  27 .ad
  28 .RS 8n
  29 value returned from a successful call to \fBnet_protocol_register()\fR.
  30 .RE
  31
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIname\fR\fR
  36 .ad
  37 .RS 8n
  38 unique name for this hook.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIhook\fR\fR
  45 .ad
  46 .RS 8n
  47 pointer to a \fBhook_t\fR structure.
  48 .RE
  49
  50 .SH DESCRIPTION
  51 .sp
  52 .LP
  53 The \fBnet_hook_register()\fR function uses hooks that allow callbacks to be
  54 registered with events that belong to a network protocol. A successful call to
  55 \fBnet_hook_register()\fR requires that a valid handle for a network protocol be
  56 provided (the \fIinfo\fR parameter), along with a unique name and a hook
  57 description that includes a reference to an available event. No two hooks on the
  58 same netstack may share a name.
  59 .sp
  60 .LP
  61 While it is possible to use the same \fBhook_t\fR structure with multiple calls
  62 to \fBnet_hook_register()\fR, it is not encouraged.
  63 .sp
  64 .LP
  65 The \fBhook_t\fR structure passed in with this function is described by
  66 \fBhook_t\fR(9S). The following describes how this structure is used.
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBh_func\fR\fR
  71 .ad
  72 .RS 23n
  73 Must be non-NULL and represent a function that fits the specified interface.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBh_name\fR\fR
  80 .ad
  81 .RS 23n
  82 Gives the hook a name that represents its owner. No duplication of \fBh_name\fR
  83 among the hooks present for an event is allowed.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBh_flags\fR\fR
  90 .ad
  91 .RS 23n
  92 Currently unused and must be set to 0.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBh_hint, h_hintvalue\fR\fR
  99 .ad
 100 .RS 23n
 101 Specify a hint to \fBnet_hook_register()\fR on how to insert this hook. If the
 102 hint cannot be specified, then an error is returned.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBh_arg;\fR\fR
 109 .ad
 110 .RS 23n
 111 May take any value that the consumer wishes to have passed back when the hook
 112 is activated.
 113 .RE
 114
 115 .SH RETURN VALUES
 116 .sp
 117 .LP
 118 If the \fBnet_hook_register()\fR function succeeds, 0 is returned. Otherwise,
 119 one of the following errors is returned:
 120 .sp
 121 .ne 2
 122 .na
 123 \fBENOMEM\fR
 124 .ad
 125 .RS 10n
 126 The system cannot allocate any more memory to support registering this hook.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fBENXIO\fR
 133 .ad
 134 .RS 10n
 135 A hook cannot be found among the given family of events.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fBEEXIST\fR
 142 .ad
 143 .RS 10n
 144 A hook with the given \fBh_name\fR already exists on that event.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fBESRCH\fR
 151 .ad
 152 .RS 10n
 153 A before or after dependency cannot be satisfied due to the hook with
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fBEBUSY\fR
 160 .ad
 161 .RS 10n
 162 The \fBh_hint\fR field specifies a hint that cannot currently be satisfied
 163 because it conflicts with another hook. An example of this might be specifying
 164 \fBHH_FIRST\fR or \fBHH_LAST\fR when another hook has already been registered
 165 with this value.
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fBESHUTDOWN\fR
 172 .ad
 173 .RS 10n
 174 The netstack corresponding to \fIinfo\fR is condemned or no longer exists.
 175
 176 .SH CONTEXT
 177 .sp
 178 .LP
 179 The \fBnet_hook_register()\fR function may be called from user  or kernel
 180 context.
 181 .SH ATTRIBUTES
 182 .sp
 183 .LP
 184 See \fBattributes\fR(5) for descriptions of the following attributes:
 185 .sp
 186
 187 .sp
 188 .TS
 189 box;
 190 c | c
 191 l | l .
 192 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 193 _
 194 Interface Stability     Committed
 195 .TE
 196
 197 .SH SEE ALSO
 198 .sp
 199 .LP
 200 \fBnet_hook_unregister\fR(9F), \fBhook_t\fR(9S)