1/* 2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28/* Copyright (c) 1998, 1999 Apple Computer, Inc. All Rights Reserved */ 29/*! 30 @header kern_event.h 31 This header defines in-kernel functions for generating kernel events as well 32 as functions for receiving kernel events using a kernel event socket. 33 */ 34 35#ifndef SYS_KERN_EVENT_H 36#define SYS_KERN_EVENT_H 37 38#include <sys/appleapiopts.h> 39#include <sys/ioccom.h> 40#include <sys/sys_domain.h> 41 42#define KEVENTS_ON 1 43#define KEV_SNDSPACE (4 * 1024) 44#define KEV_RECVSPACE (32 * 1024) 45 46#define KEV_ANY_VENDOR 0 47#define KEV_ANY_CLASS 0 48#define KEV_ANY_SUBCLASS 0 49 50/* 51 * Vendor Code 52 */ 53 54/*! 55 @defined KEV_VENDOR_APPLE 56 @discussion Apple generated kernel events use the hard coded vendor code 57 value of 1. Third party kernel events use a dynamically allocated vendor 58 code. The vendor code can be found using the SIOCGKEVVENDOR ioctl. 59*/ 60#define KEV_VENDOR_APPLE 1 61 62 63/* 64 * Definition of top-level classifications for KEV_VENDOR_APPLE 65 */ 66 67/*! 68 @defined KEV_NETWORK_CLASS 69 @discussion Network kernel event class. 70*/ 71#define KEV_NETWORK_CLASS 1 72 73/*! 74 @defined KEV_IOKIT_CLASS 75 @discussion IOKit kernel event class. 76*/ 77#define KEV_IOKIT_CLASS 2 78 79/*! 80 @defined KEV_IOKIT_CLASS 81 @discussion System kernel event class. 82*/ 83#define KEV_SYSTEM_CLASS 3 84 85/*! 86 @defined KEV_APPLESHARE_CLASS 87 @discussion AppleShare kernel event class. 88*/ 89#define KEV_APPLESHARE_CLASS 4 90 91/*! 92 @defined KEV_FIREWALL_CLASS 93 @discussion Firewall kernel event class. 94*/ 95#define KEV_FIREWALL_CLASS 5 96 97/*! 98 @struct kern_event_msg 99 @discussion This structure is prepended to all kernel events. This structure 100 is used to determine the format of the remainder of the kernel event. 101 This structure will appear on all messages received on a kernel event 102 socket. To post a kernel event, a slightly different structure is used. 103 @field total_size Total size of the kernel event message including the 104 header. 105 @field vendor_code The vendor code indicates which vendor generated the 106 kernel event. This gives every vendor a unique set of classes and 107 subclasses to use. Use the SIOCGKEVVENDOR ioctl to look up vendor codes 108 for vendors other than Apple. Apple uses KEV_VENDOR_APPLE. 109 @field kev_class The class of the kernel event. 110 @field kev_subclass The subclass of the kernel event. 111 @field id Monotonically increasing value. 112 @field event_code The event code. 113 @field event_data Any additional data about this event. Format will depend 114 on the vendor_code, kev_class, kev_subclass, and event_code. The length 115 of the event_data can be determined using total_size - 116 KEV_MSG_HEADER_SIZE. 117*/ 118struct kern_event_msg { 119 u_int32_t total_size; /* Size of entire event msg */ 120 u_int32_t vendor_code; /* For non-Apple extensibility */ 121 u_int32_t kev_class; /* Layer of event source */ 122 u_int32_t kev_subclass; /* Component within layer */ 123 u_int32_t id; /* Monotonically increasing value */ 124 u_int32_t event_code; /* unique code */ 125 u_int32_t event_data[1]; /* One or more data words */ 126}; 127 128/*! 129 @defined KEV_MSG_HEADER_SIZE 130 @discussion Size of the header portion of the kern_event_msg structure. This 131 accounts for everything right up to event_data. The size of the data can 132 be found by subtracting KEV_MSG_HEADER_SIZE from the total size from the 133 kern_event_msg. 134*/ 135#define KEV_MSG_HEADER_SIZE (offsetof(struct kern_event_msg, event_data[0])) 136 137/*! 138 @struct kev_request 139 @discussion This structure is used with the SIOCSKEVFILT and SIOCGKEVFILT to 140 set and get the control filter setting for a kernel control socket. 141 @field total_size Total size of the kernel event message including the 142 header. 143 @field vendor_code All kernel events that don't match this vendor code will 144 be ignored. KEV_ANY_VENDOR can be used to receive kernel events with any 145 vendor code. 146 @field kev_class All kernel events that don't match this class will be 147 ignored. KEV_ANY_CLASS can be used to receive kernel events with any 148 class. 149 @field kev_subclass All kernel events that don't match this subclass will be 150 ignored. KEV_ANY_SUBCLASS can be used to receive kernel events with any 151 subclass. 152*/ 153struct kev_request { 154 u_int32_t vendor_code; 155 u_int32_t kev_class; 156 u_int32_t kev_subclass; 157}; 158 159/*! 160 @defined KEV_VENDOR_CODE_MAX_STR_LEN 161 @discussion This define sets the maximum length of a string that can be used 162 to identify a vendor or kext when looking up a vendor code. 163*/ 164#define KEV_VENDOR_CODE_MAX_STR_LEN 200 165 166#pragma pack(4) 167 168/*! 169 @struct kev_vendor_code 170 @discussion This structure is used with the SIOCGKEVVENDOR ioctl to convert 171 from a string identifying a kext or vendor, in the form of a bundle 172 identifier, to a vendor code. 173 @field vendor_code After making the SIOCGKEVVENDOR ioctl call, this will 174 be filled in with the vendor code if there is one. 175 @field vendor_string A bundle style identifier. 176*/ 177struct kev_vendor_code { 178 u_int32_t vendor_code; 179 char vendor_string[KEV_VENDOR_CODE_MAX_STR_LEN]; 180}; 181 182#pragma pack() 183 184/*! 185 @defined SIOCGKEVID 186 @discussion Retrieve the current event id. Each event generated will have 187 a new idea. The next event to be generated will have an id of id+1. 188*/ 189#define SIOCGKEVID _IOR('e', 1, u_int32_t) 190 191/*! 192 @defined SIOCSKEVFILT 193 @discussion Set the kernel event filter for this socket. Kernel events not 194 matching this filter will not be received on this socket. 195*/ 196#define SIOCSKEVFILT _IOW('e', 2, struct kev_request) 197 198/*! 199 @defined SIOCGKEVFILT 200 @discussion Retrieve the kernel event filter for this socket. Kernel events 201 not matching this filter will not be received on this socket. 202*/ 203#define SIOCGKEVFILT _IOR('e', 3, struct kev_request) 204 205/*! 206 @defined SIOCGKEVVENDOR 207 @discussion Lookup the vendor code for the specified vendor. ENOENT will be 208 returned if a vendor code for that vendor string does not exist. 209*/ 210#define SIOCGKEVVENDOR _IOWR('e', 4, struct kev_vendor_code) 211 212#ifdef KERNEL 213/*! 214 @define N_KEV_VECTORS 215 @discussion The maximum number of kev_d_vectors for a kernel event. 216*/ 217#define N_KEV_VECTORS 5 218 219/*! 220 @struct kev_d_vectors 221 @discussion This structure is used to append some data to a kernel event. 222 @field data_length The length of data. 223 @field data_ptr A pointer to data. 224*/ 225struct kev_d_vectors { 226 u_int32_t data_length; /* Length of the event data */ 227 void *data_ptr; /* Pointer to event data */ 228}; 229 230/*! 231 @struct kev_msg 232 @discussion This structure is used when posting a kernel event. 233 @field vendor_code The vendor code assigned by kev_vendor_code_find. 234 @field kev_class The event's class. 235 @field kev_class The event's subclass. 236 @field kev_class The event's code. 237 @field dv An array of vectors describing additional data to be appended to 238 the kernel event. 239*/ 240struct kev_msg { 241 u_int32_t vendor_code; /* For non-Apple extensibility */ 242 u_int32_t kev_class; /* Layer of event source */ 243 u_int32_t kev_subclass; /* Component within layer */ 244 u_int32_t event_code; /* The event code */ 245 struct kev_d_vectors dv[N_KEV_VECTORS]; /* Up to n data vectors */ 246}; 247 248/*! 249 @function kev_vendor_code_find 250 @discussion Lookup a vendor_code given a unique string. If the vendor code 251 has not been used since launch, a unique integer will be assigned for 252 that string. Vendor codes will remain the same until the machine is 253 rebooted. 254 @param vendor_string A bundle style vendor identifier (i.e. com.apple). 255 @param vendor_code Upon return, a unique vendor code for use when posting 256 kernel events. 257 @result May return ENOMEM if memory constraints prevent allocation of a new 258 vendor code. 259 */ 260errno_t kev_vendor_code_find(const char *vendor_string, u_int32_t *vendor_code); 261 262/*! 263 @function kev_msg_post 264 @discussion Post a kernel event message. 265 @param event_msg A structure defining the kernel event message to post. 266 @result Will return zero upon success. May return a number of errors 267 depending on the type of failure. EINVAL indicates that there was 268 something wrong with the kerne event. The vendor code of the kernel 269 event must be assigned using kev_vendor_code_find. If the message is 270 too large, EMSGSIZE will be returned. 271 */ 272errno_t kev_msg_post(struct kev_msg *event_msg); 273 274#ifdef PRIVATE 275/* 276 * Internal version of kev_post_msg. Allows posting Apple vendor code kernel 277 * events. 278 */ 279int kev_post_msg(struct kev_msg *event); 280 281LIST_HEAD(kern_event_head, kern_event_pcb); 282 283struct kern_event_pcb { 284 LIST_ENTRY(kern_event_pcb) ev_link; /* glue on list of all PCBs */ 285 struct socket *ev_socket; /* pointer back to socket */ 286 u_int32_t vendor_code_filter; 287 u_int32_t class_filter; 288 u_int32_t subclass_filter; 289}; 290 291#define sotoevpcb(so) ((struct kern_event_pcb *)((so)->so_pcb)) 292 293 294#endif /* PRIVATE */ 295#endif /* KERNEL */ 296#endif /* SYS_KERN_EVENT_H */ 297