Mac Developer Library

Developer

kern_control.h Reference

Options
Deployment Target:

On This Page

kern_control.h Reference

This header defines an API to communicate between a kernel extension and a process outside of the kernel.

Included Headers

  • <sys/appleapiopts.h>

  • <sys/kpi_mbuf.h>

Functions

  • ctl_deregister ctl_deregister Available in OS X v10.4 through OS X v10.5

    Declaration

    Objective-C

    errno_t ctl_deregister ( kern_ctl_ref kctlref );

    Parameters

    kctlref

    The control reference of the control to unregister.

    Return Value

    0 - Kernel control was unregistered. EINVAL - The kernel control reference was invalid. EBUSY - The kernel control has clients still attached.

    Discussion

    Unregister a kernel control. A kernel extension must unregister it's kernel control(s) before unloading. If a kernel control has clients attached, this call will fail.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • ctl_enqueuedata ctl_enqueuedata Available in OS X v10.4 through OS X v10.5

    Declaration

    Objective-C

    errno_t ctl_enqueuedata ( kern_ctl_ref kctlref, u_int32_t unit, void *data, size_t len, u_int32_t flags );

    Parameters

    kctlref

    The control reference of the kernel control.

    unit

    The unit number of the kernel control instance.

    data

    A pointer to the data to send.

    len

    The length of data to send.

    flags

    Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently the only supported flags.

    Return Value

    0 - Data was enqueued to be read by the client. EINVAL - Invalid parameters. EMSGSIZE - The buffer is too large. ENOBUFS - The queue is full or there are no free mbufs.

    Discussion

    Send data from the kernel control to the client.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • ctl_enqueuembuf ctl_enqueuembuf Available in OS X v10.4 through OS X v10.5

    Declaration

    Objective-C

    errno_t ctl_enqueuembuf ( kern_ctl_ref kctlref, u_int32_t unit, mbuf_t m, u_int32_t flags );

    Parameters

    kctlref

    The control reference of the kernel control.

    unit

    The unit number of the kernel control instance.

    m

    An mbuf chain containing the data to send to the client.

    flags

    Send flags. CTL_DATA_NOWAKEUP and CTL_DATA_EOR are currently the only supported flags.

    Return Value

    0 - Data was enqueued to be read by the client. EINVAL - Invalid parameters. ENOBUFS - The queue is full.

    Discussion

    Send data stored in an mbuf chain from the kernel control to the client. The caller is responsible for freeing the mbuf chain if ctl_enqueuembuf returns an error.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • ctl_getenqueuespace ctl_getenqueuespace Available in OS X v10.4 through OS X v10.5

    Declaration

    Objective-C

    errno_t ctl_getenqueuespace ( kern_ctl_ref kctlref, u_int32_t unit, size_t *space );

    Parameters

    kctlref

    The control reference of the kernel control.

    unit

    The unit number of the kernel control instance.

    space

    The address where to return the current space available

    Return Value

    0 - Success; the amount of space is returned to caller. EINVAL - Invalid parameters.

    Discussion

    Retrieve the amount of space currently available for data to be sent from the kernel control to the client.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • ctl_register ctl_register Available in OS X v10.4 through OS X v10.5

    Declaration

    Objective-C

    errno_t ctl_register ( struct kern_ctl_reg *userkctl, kern_ctl_ref *kctlref );

    Parameters

    userkctl

    A structure defining the kernel control to be attached. The ctl_connect callback must be specified, the other callbacks are optional. If ctl_connect is set to zero, ctl_register fails with the error code EINVAL.

    kctlref

    Upon successful return, the kctlref will contain a reference to the attached kernel control. This reference is used to unregister the kernel control. This reference will also be passed in to the callbacks each time they are called.

    Return Value

    0 - Kernel control was registered. EINVAL - The registration structure was not valid. ENOMEM - There was insufficient memory. EEXIST - A controller with that id/unit is already registered.

    Discussion

    Register a kernel control. This will enable clients to connect to the kernel control using a PF_SYSTEM socket.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

Callbacks

  • Declaration

    Objective-C

    typedef errno_t ( *ctl_connect_func)( kern_ctl_ref kctlref, struct sockaddr_ctl *sac, void **unitinfo);

    Parameters

    kctlref

    The control ref for the kernel control the client is connecting to.

    sac

    The address used to connect to this control. The field sc_unit contains the unit number of the kernel control instance the client is connecting to. If CTL_FLAG_REG_ID_UNIT was set when the kernel control was registered, sc_unit is the ctl_unit of the kern_ctl_reg structure. If CTL_FLAG_REG_ID_UNIT was not set when the kernel control was registered, sc_unit is the dynamically allocated unit number of the new kernel control instance that is used for this connection.

    unitinfo

    A placeholder for a pointer to the optional user-defined private data associated with this kernel control instance. This opaque info will be provided to the user when the rest of the callback routines are executed. For example, it can be used to pass a pointer to an instance-specific data structure in order for the user to keep track of the states related to this kernel control instance.

    Discussion

    The ctl_connect_func is used to receive notification of a client connecting to the kernel control.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • Declaration

    Objective-C

    typedef errno_t ( *ctl_disconnect_func)( kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo);

    Parameters

    kctlref

    The control ref for the kernel control instance the client has disconnected from.

    unit

    The unit number of the kernel control instance the client has disconnected from.

    unitinfo

    The user-defined private data initialized by the ctl_connect_func callback.

    Discussion

    The ctl_disconnect_func is used to receive notification that a client has disconnected from the kernel control. This usually happens when the socket is closed. If this is the last socket attached to your kernel control, you may unregister your kernel control from this callback.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • Declaration

    Objective-C

    typedef errno_t ( *ctl_getopt_func)( kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, int opt, void *data, size_t *len);

    Parameters

    kctlref

    The control ref of the kernel control.

    unit

    The unit number of the kernel control instance.

    unitinfo

    The user-defined private data initialized by the ctl_connect_func callback.

    opt

    The socket option.

    data

    A buffer to copy the results in to. May be NULL, see discussion.

    len

    A pointer to the length of the buffer. This should be set to the length of the buffer used before returning.

    Discussion

    The ctl_getopt_func is used to handle client get socket option requests for the SYSPROTO_CONTROL option level. A buffer is allocated for storage and passed to your function. The length of that buffer is also passed. Upon return, you should set *len to length of the buffer used. In some cases, data may be NULL. When this happens, *len should be set to the length you would have returned had data not been NULL. If the buffer is too small, return an error.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • Declaration

    Objective-C

    typedef errno_t ( *ctl_send_func)( kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, mbuf_t m, int flags);

    Parameters

    kctlref

    The control ref of the kernel control.

    unit

    The unit number of the kernel control instance the client has connected to.

    unitinfo

    The user-defined private data initialized by the ctl_connect_func callback.

    m

    The data sent by the client to the kernel control in an mbuf chain. Your function is responsible for releasing the mbuf chain.

    flags

    The flags specified by the client when calling send/sendto/sendmsg (MSG_OOB/MSG_DONTROUTE).

    Discussion

    The ctl_send_func is used to receive data sent from the client to the kernel control.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • Declaration

    Objective-C

    typedef errno_t ( *ctl_setopt_func)( kern_ctl_ref kctlref, u_int32_t unit, void *unitinfo, int opt, void *data, size_t len);

    Parameters

    kctlref

    The control ref of the kernel control.

    unit

    The unit number of the kernel control instance.

    unitinfo

    The user-defined private data initialized by the ctl_connect_func callback.

    opt

    The socket option.

    data

    A pointer to the socket option data. The data has already been copied in to the kernel for you.

    len

    The length of the socket option data.

    Discussion

    The ctl_setopt_func is used to handle set socket option calls for the SYSPROTO_CONTROL option level.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

Data Types

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    typedef void * kern_ctl_ref;

    Discussion

    A control reference is used to track an attached kernel control. Registering a kernel control will create a kernel control reference. This reference is required for sending data or removing the kernel control. This reference will be passed to callbacks for that kernel control.

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.5.

  • Declaration

    Objective-C

    struct ctl_event_data { u_int32_t ctl_id; /* Kernel Controller ID */ u_int32_t ctl_unit; };

    Fields

    ctl_id

    The kernel control id.

    ctl_unit

    The kernel control unit.

    Discussion

    This structure is used for KEV_CTL_SUBCLASS kernel events.

  • Declaration

    Objective-C

    struct ctl_info { u_int32_t ctl_id; /* Kernel Controller ID */ char ctl_name[ 96]; /* Kernel Controller Name (a C string) */ };

    Fields

    ctl_id

    The kernel control id, filled out upon return.

    ctl_name

    The kernel control name to find.

    Discussion

    This structure is used with the CTLIOCGINFO ioctl to translate from a kernel control name to a control id.

  • Declaration

    Objective-C

    struct kern_ctl_reg { /* control information */ char ctl_name[ 96]; u_int32_t ctl_id; u_int32_t ctl_unit; /* control settings */ u_int32_t ctl_flags; u_int32_t ctl_sendsize; u_int32_t ctl_recvsize; /* Dispatch functions */ ctl_connect_func ctl_connect; ctl_disconnect_func ctl_disconnect; ctl_send_func ctl_send; ctl_setopt_func ctl_setopt; ctl_getopt_func ctl_getopt; };

    Fields

    ctl_name

    A Bundle ID string of up to MAX_KCTL_NAME bytes (including the ending zero). This string should not be empty.

    ctl_id

    The control ID may be dynamically assigned or it can be a 32-bit creator code assigned by DTS. For a DTS assigned creator code the CTL_FLAG_REG_ID_UNIT flag must be set. For a dynamically assigned control ID, do not set the CTL_FLAG_REG_ID_UNIT flag. The value of the dynamically assigned control ID is set to this field when the registration succeeds.

    ctl_unit

    A separate unit number to register multiple units that share the same control ID with DTS assigned creator code when the CTL_FLAG_REG_ID_UNIT flag is set. This field is ignored for a dynamically assigned control ID.

    ctl_flags

    CTL_FLAG_PRIVILEGED and/or CTL_FLAG_REG_ID_UNIT.

    ctl_sendsize

    Override the default send size. If set to zero, the default send size will be used, and this default value is set to this field to be retrieved by the caller.

    ctl_recvsize

    Override the default receive size. If set to zero, the default receive size will be used, and this default value is set to this field to be retrieved by the caller.

    ctl_connect

    Specify the function to be called whenever a client connects to the kernel control. This field must be specified.

    ctl_disconnect

    Specify a function to be called whenever a client disconnects from the kernel control.

    ctl_send

    Specify a function to handle data send from the client to the kernel control.

    ctl_setopt

    Specify a function to handle set socket option operations for the kernel control.

    ctl_getopt

    Specify a function to handle get socket option operations for the kernel control.

    Discussion

    This structure defines the properties of a kernel control being registered.

  • Declaration

    Objective-C

    struct sockaddr_ctl { u_char sc_len; /* depends on size of bundle ID string */ u_char sc_family; /* AF_SYSTEM */ u_int16_t ss_sysaddr; /* AF_SYS_KERNCONTROL */ u_int32_t sc_id; /* Controller unique identifier */ u_int32_t sc_unit; /* Developer private unit number */ u_int32_t sc_reserved[5]; };

    Fields

    sc_len

    The length of the structure.

    sc_family

    AF_SYSTEM.

    ss_sysaddr

    AF_SYS_KERNCONTROL.

    sc_id

    Controller unique identifier.

    sc_unit

    Kernel controller private unit number.

    sc_reserved

    Reserved, must be set to zero.

    Discussion

    The controller address structure is used to establish contact between a user client and a kernel controller. The sc_id/sc_unit uniquely identify each controller. sc_id is a unique identifier assigned to the controller. The identifier can be assigned by the system at registration time or be a 32-bit creator code obtained from Apple Computer. sc_unit is a unit number for this sc_id, and is privately used by the kernel controller to identify several instances of the controller.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    #define CTL_DATA_EOR 0x2 #define CTL_DATA_NOWAKEUP 0x1 #define CTL_FLAG_PRIVILEGED 0x1 #define CTL_FLAG_REG_ID_UNIT 0x2 #define CTL_FLAG_REG_SOCK_STREAM 0x4 #define CTLIOCGCOUNT _IOR('N', 2, int) /* get number of control structures registered */ #define CTLIOCGINFO _IOWR('N', 3, struct ctl_info) /* get id from name */ #define KEV_CTL_DEREGISTERED 2 /* a controller disappears */ #define KEV_CTL_REGISTERED 1 /* a new controller appears */ #define KEV_CTL_SUBCLASS 2 #define MAX_KCTL_NAME 96

    Constants

    • CTL_DATA_EOR

      CTL_DATA_EOR

      The CTL_DATA_EOR flag can be used for the enqueue data and enqueue mbuf functions to mark the end of a record.

      Available in OS X v10.4 through OS X v10.5.

    • CTL_DATA_NOWAKEUP

      CTL_DATA_NOWAKEUP

      The CTL_DATA_NOWAKEUP flag can be used for the enqueue data and enqueue mbuf functions to indicate that the process should not be woken up yet. This is useful when you want to enqueue data using more than one call but only want to wake up the client after all of the data has been enqueued.

      Available in OS X v10.4 through OS X v10.5.

    • CTL_FLAG_PRIVILEGED

      CTL_FLAG_PRIVILEGED

      The CTL_FLAG_PRIVILEGED flag is passed in ctl_flags. If this flag is set, only privileged processes may attach to this kernel control.

      Available in OS X v10.4 through OS X v10.5.

    • CTL_FLAG_REG_ID_UNIT

      CTL_FLAG_REG_ID_UNIT

      The CTL_FLAG_REG_ID_UNIT flag is passed to indicate that the ctl_id specified should be used. If this flag is not present, a unique ctl_id will be dynamically assigned to your kernel control. The CTLIOCGINFO ioctl can be used by the client to find the dynamically assigned id based on the control name specified in ctl_name.

      Available in OS X v10.4 through OS X v10.5.

    • CTL_FLAG_REG_SOCK_STREAM

      CTL_FLAG_REG_SOCK_STREAM

      Use the CTL_FLAG_REG_SOCK_STREAM flag when client need to open socket of type SOCK_STREAM to communicate with the kernel control. By default kernel control sockets are of type SOCK_DGRAM.

      Available in OS X v10.4 through OS X v10.5.

    • CTLIOCGCOUNT

      CTLIOCGCOUNT

      The CTLIOCGCOUNT ioctl can be used to determine the number of kernel controllers registered.

      Available in OS X v10.2 through OS X v10.5.

    • CTLIOCGINFO

      CTLIOCGINFO

      The CTLIOCGINFO ioctl can be used to convert a kernel control name to a kernel control id.

      Available in OS X v10.4 through OS X v10.5.

    • KEV_CTL_DEREGISTERED

      KEV_CTL_DEREGISTERED

      The event code indicating a controller was unregistered. The data portion will contain a ctl_event_data.

      Available in OS X v10.2 through OS X v10.5.

    • KEV_CTL_REGISTERED

      KEV_CTL_REGISTERED

      The event code indicating a new controller was registered. The data portion will contain a ctl_event_data.

      Available in OS X v10.2 through OS X v10.5.

    • KEV_CTL_SUBCLASS

      KEV_CTL_SUBCLASS

      The kernel event subclass for kernel control events.

      Available in OS X v10.2 through OS X v10.5.

    • MAX_KCTL_NAME

      MAX_KCTL_NAME

      Kernel control names must be no longer than MAX_KCTL_NAME.

      Available in OS X v10.4 through OS X v10.5.

    Import Statement