kern_event.h Reference

Declared in
kern_event.h

Overview

This header defines in-kernel functions for generating kernel events as well as functions for receiving kernel events using a kernel event socket.

Included Headers

  • <sys/appleapiopts.h>

  • <sys/ioccom.h>

  • <sys/sys_domain.h>

Functions

See the Overview section above for header-level documentation.

kev_msg_post

errno_t kev_msg_post(
   struct kev_msg *event_msg);
Parameters
event_msg

A structure defining the kernel event message to post.

Return Value

Will return zero upon success. May return a number of errors depending on the type of failure. EINVAL indicates that there was something wrong with the kerne event. The vendor code of the kernel event must be assigned using kev_vendor_code_find. If the message is too large, EMSGSIZE will be returned.

Discussion

Post a kernel event message.

Availability
  • Available in OS X v10.4 and later.
Declared In
kern_event.h

kev_vendor_code_find

errno_t kev_vendor_code_find(
   const char *vendor_string,
   u_int32_t *vendor_code);
Parameters
vendor_string

A bundle style vendor identifier(i.e. com.apple).

vendor_code

Upon return, a unique vendor code for use when posting kernel events.

Return Value

May return ENOMEM if memory constraints prevent allocation of a new vendor code.

Discussion

Lookup a vendor_code given a unique string. If the vendor code has not been used since launch, a unique integer will be assigned for that string. Vendor codes will remain the same until the machine is rebooted.

Availability
  • Available in OS X v10.4 and later.
Declared In
kern_event.h

Data Types

See the Overview section above for header-level documentation.

kern_event_msg

struct kern_event_msg {
   u_int32_t total_size; /* Size of entire event msg */
   u_int32_t vendor_code; /* For non-Apple extensibility */
   u_int32_t kev_class; /* Layer of event source */
   u_int32_t kev_subclass; /* Component within layer */
   u_int32_t id; /* Monotonically increasing value */
   u_int32_t event_code; /* unique code */
   u_int32_t event_data[1]; /* One or more data words */
};
Fields
total_size

Total size of the kernel event message including the header.

vendor_code

The vendor code indicates which vendor generated the kernel event. This gives every vendor a unique set of classes and subclasses to use. Use the SIOCGKEVVENDOR ioctl to look up vendor codes for vendors other than Apple. Apple uses KEV_VENDOR_APPLE.

kev_class

The class of the kernel event.

kev_subclass

The subclass of the kernel event.

id

Monotonically increasing value.

event_code

The event code.

event_data

Any additional data about this event. Format will depend on the vendor_code, kev_class, kev_subclass, and event_code. The length of the event_data can be determined using total_size - KEV_MSG_HEADER_SIZE.

Discussion

This structure is prepended to all kernel events. This structure is used to determine the format of the remainder of the kernel event. This structure will appear on all messages received on a kernel event socket. To post a kernel event, a slightly different structure is used.

Availability
  • Available in OS X v10.9 and later.
Declared In
kern_event.h

kev_d_vectors

struct kev_d_vectors {
   u_int32_t data_length; /* Length of the event data */
   void *data_ptr; /* Pointer to event data */
};
Fields
data_length

The length of data.

data_ptr

A pointer to data.

Discussion

This structure is used to append some data to a kernel event.

Availability
  • Available in OS X v10.9 and later.
Declared In
kern_event.h

kev_msg

struct kev_msg {
   u_int32_t vendor_code; /* For non-Apple extensibility */
   u_int32_t kev_class; /* Layer of event source */
   u_int32_t kev_subclass; /* Component within layer */
   u_int32_t event_code; /* The event code */
   struct kev_d_vectors dv[ 5]; /* Up to n data vectors */
};
Fields
vendor_code

The vendor code assigned by kev_vendor_code_find.

kev_class

The event's class.

The event's subclass.

The event's code.

dv

An array of vectors describing additional data to be appended to the kernel event.

Discussion

This structure is used when posting a kernel event.

Availability
  • Available in OS X v10.9 and later.
Declared In
kern_event.h

kev_request

struct kev_request {
   u_int32_t vendor_code;
   u_int32_t kev_class;
   u_int32_t kev_subclass;
};
Fields
total_size

Total size of the kernel event message including the header.

vendor_code

All kernel events that don't match this vendor code will be ignored. KEV_ANY_VENDOR can be used to receive kernel events with any vendor code.

kev_class

All kernel events that don't match this class will be ignored. KEV_ANY_CLASS can be used to receive kernel events with any class.

kev_subclass

All kernel events that don't match this subclass will be ignored. KEV_ANY_SUBCLASS can be used to receive kernel events with any subclass.

Discussion

This structure is used with the SIOCSKEVFILT and SIOCGKEVFILT to set and get the control filter setting for a kernel control socket.

Availability
  • Available in OS X v10.9 and later.
Declared In
kern_event.h

kev_vendor_code

struct kev_vendor_code {
   u_int32_t vendor_code;
   char vendor_string[ 200];
};
Fields
vendor_code

After making the SIOCGKEVVENDOR ioctl call, this will be filled in with the vendor code if there is one.

vendor_string

A bundle style identifier.

Discussion

This structure is used with the SIOCGKEVVENDOR ioctl to convert from a string identifying a kext or vendor, in the form of a bundle identifier, to a vendor code.

Availability
  • Available in OS X v10.9 and later.
Declared In
kern_event.h

Constants

See the Overview section above for header-level documentation.

Miscellaneous Defines

   
#define KEV_APPLESHARE_CLASS 4
#define KEV_FIREWALL_CLASS 5
#define KEV_IEEE80211_CLASS 6
#define KEV_IOKIT_CLASS 2
#define KEV_MSG_HEADER_SIZE (offsetof(struct kern_event_msg,
   event_data[0]))
#define KEV_NETWORK_CLASS 1
#define KEV_SYSTEM_CLASS 3
#define KEV_VENDOR_APPLE 1
#define KEV_VENDOR_CODE_MAX_STR_LEN 200
#define N_KEV_VECTORS 5
#define SIOCGKEVFILT _IOR('e',
   3,
   struct kev_request)
#define SIOCGKEVID _IOR('e',
   1,
   u_int32_t)
#define SIOCGKEVVENDOR _IOWR('e',
   4,
   struct kev_vendor_code)
#define SIOCSKEVFILT _IOW('e',
   2,
   struct kev_request)
Constants
KEV_APPLESHARE_CLASS

AppleShare kernel event class.

Available in OS X v10.4 and later.

Declared in kern_event.h.

KEV_FIREWALL_CLASS

Firewall kernel event class.

Available in OS X v10.5 and later.

Declared in kern_event.h.

KEV_IEEE80211_CLASS

IEEE 802.11 kernel event class.

Available in OS X v10.9 and later.

Declared in kern_event.h.

KEV_IOKIT_CLASS

IOKit kernel event class.

Available in OS X v10.0 and later.

Declared in kern_event.h.

KEV_MSG_HEADER_SIZE

Size of the header portion of the kern_event_msg structure. This accounts for everything right up to event_data. The size of the data can be found by subtracting KEV_MSG_HEADER_SIZE from the total size from the kern_event_msg.

Available in OS X v10.0 and later.

Declared in kern_event.h.

KEV_NETWORK_CLASS

Network kernel event class.

Available in OS X v10.0 and later.

Declared in kern_event.h.

KEV_SYSTEM_CLASS

System kernel event class.

Available in OS X v10.2 and later.

Declared in kern_event.h.

KEV_VENDOR_APPLE

Apple generated kernel events use the hard coded vendor code value of 1. Third party kernel events use a dynamically allocated vendor code. The vendor code can be found using the SIOCGKEVVENDOR ioctl.

Available in OS X v10.0 and later.

Declared in kern_event.h.

KEV_VENDOR_CODE_MAX_STR_LEN

This define sets the maximum length of a string that can be used to identify a vendor or kext when looking up a vendor code.

Available in OS X v10.4 and later.

Declared in kern_event.h.

N_KEV_VECTORS

The maximum number of kev_d_vectors for a kernel event.

Available in OS X v10.4 and later.

Declared in kern_event.h.

SIOCGKEVFILT

Retrieve the kernel event filter for this socket. Kernel events not matching this filter will not be received on this socket.

Available in OS X v10.0 and later.

Declared in kern_event.h.

SIOCGKEVID

Retrieve the current event id. Each event generated will have a new id. The next event to be generated will have an id of id+1.

Available in OS X v10.0 and later.

Declared in kern_event.h.

SIOCGKEVVENDOR

Lookup the vendor code for the specified vendor. ENOENT will be returned if a vendor code for that vendor string does not exist.

Available in OS X v10.4 and later.

Declared in kern_event.h.

SIOCSKEVFILT

Set the kernel event filter for this socket. Kernel events not matching this filter will not be received on this socket.

Available in OS X v10.0 and later.

Declared in kern_event.h.