Mac Developer Library

Developer

IOKitLib.h Reference

Options
Deployment Target:

On This Page
Language:

IOKitLib.h Reference

IOKitLib implements non-kernel task access to common IOKit object types - IORegistryEntry, IOService, IOIterator etc. These functions are generic - families may provide API that is more specific.

IOKitLib represents IOKit objects outside the kernel with the types io_object_t, io_registry_entry_t, io_service_t, & io_connect_t. Function names usually begin with the type of object they are compatible with - eg. IOObjectRelease can be used with any io_object_t. Inside the kernel, the c++ class hierarchy allows the subclasses of each object type to receive the same requests from user level clients, for example in the kernel, IOService is a subclass of IORegistryEntry, which means any of the IORegistryEntryXXX functions in IOKitLib may be used with io_service_t's as well as io_registry_t's. There are functions available to introspect the class of the kernel object which any io_object_t et al. represents. IOKit objects returned by all functions should be released with IOObjectRelease.

Included Headers

  • <sys/cdefs.h>

  • types.h

  • <mach/mach_types.h>

  • <mach/mach_init.h>

  • <CoreFoundation/CFBase.h>

  • <CoreFoundation/CFDictionary.h>

  • <CoreFoundation/CFRunLoop.h>

  • <IOKit/IOTypes.h>

  • <IOKit/IOKitKeys.h>

  • <IOKit/OSMessageNotification.h>

  • <AvailabilityMacros.h>

  • <dispatch/dispatch.h>

Functions

  • Create a matching dictionary that specifies an IOService match based on BSD device name.

    Declaration

    Objective-C

    OSDictionary * IOBSDNameMatching ( const char *name );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    options

    No options are currently defined.

    bsdName

    The BSD name, as a const char *.

    Return Value

    The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller.

    Discussion

    IOServices that represent BSD devices have an associated BSD name. This function creates a matching dictionary that will match IOService's with a given BSD name.

    Import Statement

    Objective-C

    #include <IOLib.h>;

    Availability

    Available in OS X v10.0 and later.

  • Inform a connection of a second connection.

    Declaration

    Swift

    func IOConnectAddClient(_ connect: io_connect_t, _ client: io_connect_t) -> kern_return_t

    Objective-C

    kern_return_t IOConnectAddClient ( io_connect_t connect, io_connect_t client );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    client

    Another connect handle created by IOServiceOpen.

    Return Value

    A kern_return_t error code returned by the family.

    Discussion

    This is a generic method to inform a family connection of a second connection, and is rarely used.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Adds a reference to the connect handle.

    Declaration

    Swift

    func IOConnectAddRef(_ connect: io_connect_t) -> kern_return_t

    Objective-C

    kern_return_t IOConnectAddRef ( io_connect_t connect );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    Return Value

    A kern_return_t error code.

    Discussion

    Adds a reference to the connect handle.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the IOService a connect handle was opened on.

    Declaration

    Swift

    func IOConnectGetService(_ connect: io_connect_t, _ service: UnsafeMutablePointer<io_service_t>) -> kern_return_t

    Objective-C

    kern_return_t IOConnectGetService ( io_connect_t connect, io_service_t *service );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    service

    On succes, the service handle the connection was opened on, which should be released with IOObjectRelease.

    Return Value

    A kern_return_t error code.

    Discussion

    Finds the service object a connection was opened on.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Map hardware or shared memory into the caller's task.

    Declaration

    Swift

    func IOConnectMapMemory(_ connect: io_connect_t, _ memoryType: UInt32, _ intoTask: task_port_t, _ atAddress: UnsafeMutablePointer<mach_vm_address_t>, _ ofSize: UnsafeMutablePointer<mach_vm_size_t>, _ options: IOOptionBits) -> kern_return_t

    Objective-C

    kern_return_t IOConnectMapMemory ( io_connect_t connect, uint32_t memoryType, task_port_t intoTask, vm_address_t *atAddress, vm_size_t *ofSize, IOOptionBits options );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    memoryType

    What is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings.

    intoTask

    The task port for the task in which to create the mapping. This may be different to the task which the opened the connection.

    atAddress

    An in/out parameter - if the kIOMapAnywhere option is not set, the caller should pass the address where it requests the mapping be created, otherwise nothing need to set on input. The address of the mapping created is passed back on sucess.

    ofSize

    The size of the mapping created is passed back on success.

    Return Value

    A kern_return_t error code.

    Discussion

    This is a generic method to create a mapping in the callers task. The family will interpret the type parameter to determine what sort of mapping is being requested. Cache modes and placed mappings may be requested by the caller.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Map hardware or shared memory into the caller's task.

    Declaration

    Swift

    func IOConnectMapMemory64(_ connect: io_connect_t, _ memoryType: UInt32, _ intoTask: task_port_t, _ atAddress: UnsafeMutablePointer<mach_vm_address_t>, _ ofSize: UnsafeMutablePointer<mach_vm_size_t>, _ options: IOOptionBits) -> kern_return_t

    Objective-C

    kern_return_t IOConnectMapMemory64 ( io_connect_t connect, uint32_t memoryType, task_port_t intoTask, mach_vm_address_t *atAddress, mach_vm_size_t *ofSize, IOOptionBits options );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    memoryType

    What is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings.

    intoTask

    The task port for the task in which to create the mapping. This may be different to the task which the opened the connection.

    atAddress

    An in/out parameter - if the kIOMapAnywhere option is not set, the caller should pass the address where it requests the mapping be created, otherwise nothing need to set on input. The address of the mapping created is passed back on sucess.

    ofSize

    The size of the mapping created is passed back on success.

    Return Value

    A kern_return_t error code.

    Discussion

    This is a generic method to create a mapping in the callers task. The family will interpret the type parameter to determine what sort of mapping is being requested. Cache modes and placed mappings may be requested by the caller.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.5 and later.

  • Remove a reference to the connect handle.

    Declaration

    Swift

    func IOConnectRelease(_ connect: io_connect_t) -> kern_return_t

    Objective-C

    kern_return_t IOConnectRelease ( io_connect_t connect );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    Return Value

    A kern_return_t error code.

    Discussion

    Removes a reference to the connect handle. If the last reference is removed an implicit IOServiceClose is performed.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Set CF container based properties on a connection.

    Declaration

    Swift

    func IOConnectSetCFProperties(_ connect: io_connect_t, _ properties: AnyObject!) -> kern_return_t

    Objective-C

    kern_return_t IOConnectSetCFProperties ( io_connect_t connect, CFTypeRef properties );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    properties

    A CF container - commonly a CFDictionary but this is not enforced. The container should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects.

    Return Value

    A kern_return_t error code returned by the family.

    Discussion

    This is a generic method to pass a CF container of properties to the connection. The properties are interpreted by the family and commonly represent configuration settings, but may be interpreted as anything.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Set a CF container based property on a connection.

    Declaration

    Swift

    func IOConnectSetCFProperty(_ connect: io_connect_t, _ propertyName: CFString!, _ property: AnyObject!) -> kern_return_t

    Objective-C

    kern_return_t IOConnectSetCFProperty ( io_connect_t connect, CFStringRef propertyName, CFTypeRef property );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    propertyName

    The name of the property as a CFString.

    property

    A CF container - should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects.

    Return Value

    A kern_return_t error code returned by the object.

    Discussion

    This is a generic method to pass a CF property to the connection. The property is interpreted by the family and commonly represent configuration settings, but may be interpreted as anything.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Set a port to receive family specific notifications.

    Declaration

    Swift

    func IOConnectSetNotificationPort(_ connect: io_connect_t, _ type: UInt32, _ port: mach_port_t, _ reference: UInt) -> kern_return_t

    Objective-C

    kern_return_t IOConnectSetNotificationPort ( io_connect_t connect, uint32_t type, mach_port_t port, uintptr_t reference );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    type

    The type of notification requested, not interpreted by IOKit and family defined.

    port

    The port to which to send notifications.

    reference

    Some families may support passing a reference parameter for the callers use with the notification.

    Return Value

    A kern_return_t error code.

    Discussion

    This is a generic method to pass a mach port send right to be be used by family specific notifications.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Remove a mapping made with IOConnectMapMemory.

    Declaration

    Swift

    func IOConnectUnmapMemory(_ connect: io_connect_t, _ memoryType: UInt32, _ fromTask: task_port_t, _ atAddress: mach_vm_address_t) -> kern_return_t

    Objective-C

    kern_return_t IOConnectUnmapMemory ( io_connect_t connect, uint32_t memoryType, task_port_t fromTask, vm_address_t atAddress );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    memoryType

    The memory type originally requested in IOConnectMapMemory.

    fromTask

    The task port for the task in which to remove the mapping. This may be different to the task which the opened the connection.

    atAddress

    The address of the mapping to be removed.

    Return Value

    A kern_return_t error code.

    Discussion

    This is a generic method to remove a mapping in the callers task.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Remove a mapping made with IOConnectMapMemory64.

    Declaration

    Swift

    func IOConnectUnmapMemory64(_ connect: io_connect_t, _ memoryType: UInt32, _ fromTask: task_port_t, _ atAddress: mach_vm_address_t) -> kern_return_t

    Objective-C

    kern_return_t IOConnectUnmapMemory64 ( io_connect_t connect, uint32_t memoryType, task_port_t fromTask, mach_vm_address_t atAddress );

    Parameters

    connect

    The connect handle created by IOServiceOpen.

    memoryType

    The memory type originally requested in IOConnectMapMemory.

    fromTask

    The task port for the task in which to remove the mapping. This may be different to the task which the opened the connection.

    atAddress

    The address of the mapping to be removed.

    Return Value

    A kern_return_t error code.

    Discussion

    This is a generic method to remove a mapping in the callers task.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.5 and later.

  • Creates and returns a mach port suitable for receiving IOKit messages of the specified type.

    Declaration

    Swift

    func IOCreateReceivePort(_ msgType: UInt32, _ recvPort: UnsafeMutablePointer<mach_port_t>) -> kern_return_t

    Objective-C

    kern_return_t IOCreateReceivePort ( uint32_t msgType, mach_port_t *recvPort );

    Parameters

    msgType

    Type of message to be sent to this port (kOSNotificationMessageID or kOSAsyncCompleteMessageID)

    recvPort

    The created port is returned.

    Return Value

    A kern_return_t error code.

    Discussion

    In the future IOKit may use specialized messages and ports instead of the standard ports created by mach_port_allocate(). Use this function instead of mach_port_allocate() to ensure compatibility with future revisions of IOKit.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Dispatches callback notifications from a mach message.

    Declaration

    Swift

    func IODispatchCalloutFromMessage(_ unused: UnsafeMutablePointer<Void>, _ msg: UnsafeMutablePointer<mach_msg_header_t>, _ reference: UnsafeMutablePointer<Void>)

    Objective-C

    void IODispatchCalloutFromMessage ( void *unused, mach_msg_header_t *msg, void *reference );

    Parameters

    unused

    Not used, set to zero.

    msg

    A pointer to the message received.

    reference

    Pass the IONotificationPortRef for the object.

    Discussion

    A notification object may deliver notifications to a mach messaging client, which should call this function to generate the callbacks associated with the notifications arriving on the port.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Checks an iterator is still valid.

    Declaration

    Swift

    func IOIteratorIsValid(_ iterator: io_iterator_t) -> boolean_t

    Objective-C

    boolean_t IOIteratorIsValid ( io_iterator_t iterator );

    Parameters

    iterator

    An IOKit iterator handle.

    Return Value

    True if the iterator handle is valid, otherwise false is returned.

    Discussion

    Some iterators will be made invalid if changes are made to the structure they are iterating over. This function checks the iterator is still valid and should be called when IOIteratorNext returns zero. An invalid iterator can be reset and the iteration restarted.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the next object in an iteration.

    Declaration

    Swift

    func IOIteratorNext(_ iterator: io_iterator_t) -> io_object_t

    Objective-C

    io_object_t IOIteratorNext ( io_iterator_t iterator );

    Parameters

    iterator

    An IOKit iterator handle.

    Return Value

    If the iterator handle is valid, the next element in the iteration is returned, otherwise zero is returned. The element should be released by the caller when it is finished.

    Discussion

    This function returns the next object in an iteration, or zero if no more remain or the iterator is invalid.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Resets an iteration back to the beginning.

    Declaration

    Swift

    func IOIteratorReset(_ iterator: io_iterator_t)

    Objective-C

    void IOIteratorReset ( io_iterator_t iterator );

    Parameters

    iterator

    An IOKit iterator handle.

    Discussion

    If an iterator is invalid, or if the caller wants to start over, IOIteratorReset will set the iteration back to the beginning.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the busyState of all IOServices.

    Declaration

    Swift

    func IOKitGetBusyState(_ masterPort: mach_port_t, _ busyState: UnsafeMutablePointer<UInt32>) -> kern_return_t

    Objective-C

    kern_return_t IOKitGetBusyState ( mach_port_t masterPort, uint32_t *busyState );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    busyState

    The busyState count is returned.

    Return Value

    A kern_return_t error code.

    Discussion

    Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService, its busyState is increased by one. Change in busyState to or from zero also changes the IOService's provider's busyState by one, which means that an IOService is marked busy when any of the above activities is ocurring on it or any of its clients. IOKitGetBusyState returns the busy state of the root of the service plane which reflects the busy state of all IOServices.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Wait for a all IOServices' busyState to be zero.

    Declaration

    Swift

    func IOKitWaitQuiet(_ masterPort: mach_port_t, _ waitTime: UnsafeMutablePointer<mach_timespec_t>) -> kern_return_t

    Objective-C

    kern_return_t IOKitWaitQuiet ( mach_port_t masterPort, mach_timespec_t *waitTime );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    waitTime

    Specifies a maximum time to wait.

    Return Value

    Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess.

    Discussion

    Blocks the caller until all IOServices are non busy, see IOKitGetBusyState.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the mach port used to initiate communication with IOKit.

    Declaration

    Swift

    func IOMasterPort(_ bootstrapPort: mach_port_t, _ masterPort: UnsafeMutablePointer<mach_port_t>) -> kern_return_t

    Objective-C

    kern_return_t IOMasterPort ( mach_port_t bootstrapPort, mach_port_t *masterPort );

    Parameters

    bootstrapPort

    Pass MACH_PORT_NULL for the default.

    masterPort

    The master port is returned.

    Return Value

    A kern_return_t error code.

    Discussion

    Functions that don't specify an existing object require the IOKit master port to be passed. This function obtains that port.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a notification object for receiving IOKit notifications of new devices or state changes.

    Declaration

    Swift

    func IONotificationPortCreate(_ masterPort: mach_port_t) -> Unmanaged<IONotificationPort>!

    Objective-C

    IONotificationPortRef IONotificationPortCreate ( mach_port_t masterPort );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    Return Value

    A reference to the notification object.

    Discussion

    Creates the notification object to receive notifications from IOKit of new device arrivals or state changes. The notification object can be supply a CFRunLoopSource, or mach_port_t to be used to listen for events.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Destroys a notification object created with IONotificationPortCreate. Also destroys any mach_port's or CFRunLoopSources obatined from IONotificationPortGetRunLoopSource or IONotificationPortGetMachPort

    Declaration

    Swift

    func IONotificationPortDestroy(_ notify: IONotificationPort!)

    Objective-C

    void IONotificationPortDestroy ( IONotificationPortRef notify );

    Parameters

    notify

    A reference to the notification object.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a mach_port to be used to listen for notifications.

    Declaration

    Swift

    func IONotificationPortGetMachPort(_ notify: IONotificationPort!) -> mach_port_t

    Objective-C

    mach_port_t IONotificationPortGetMachPort ( IONotificationPortRef notify );

    Parameters

    notify

    The notification object.

    Return Value

    A mach_port for the notification object.

    Discussion

    A notification object may deliver notifications to a mach messaging client if they listen for messages on the port obtained from this function. Callbacks associated with the notifications may be delivered by calling IODispatchCalloutFromMessage with messages received.

    The caller should not release this mach_port_t. Just call IONotificationPortDestroy to dispose of the mach_port_t and IONotificationPortRef when done.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a CFRunLoopSource to be used to listen for notifications.

    Declaration

    Swift

    func IONotificationPortGetRunLoopSource(_ notify: IONotificationPort!) -> Unmanaged<CFRunLoopSource>!

    Objective-C

    CFRunLoopSourceRef IONotificationPortGetRunLoopSource ( IONotificationPortRef notify );

    Parameters

    notify

    The notification object.

    Return Value

    A CFRunLoopSourceRef for the notification object.

    Discussion

    A notification object may deliver notifications to a CFRunLoop by adding the run loop source returned by this function to the run loop.

    The caller should not release this CFRunLoopSource. Just call IONotificationPortDestroy to dispose of the IONotificationPortRef and the CFRunLoopSource when done.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Sets a dispatch queue to be used to listen for notifications.

    Declaration

    Swift

    func IONotificationPortSetDispatchQueue(_ notify: IONotificationPort!, _ queue: dispatch_queue_t!)

    Objective-C

    void IONotificationPortSetDispatchQueue ( IONotificationPortRef notify, dispatch_queue_t queue );

    Parameters

    notify

    The notification object.

    queue

    A dispatch queue.

    Discussion

    A notification object may deliver notifications to a dispatch client.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.6 and later.

  • Performs an OSDynamicCast operation on an IOKit object.

    Declaration

    Swift

    func IOObjectConformsTo(_ object: io_object_t, _ className: UnsafePointer<Int8>) -> boolean_t

    Objective-C

    boolean_t IOObjectConformsTo ( io_object_t object, const io_name_t className );

    Parameters

    object

    An IOKit object.

    className

    The name of the class, as a C-string.

    Return Value

    If the object handle is valid, and represents an object in the kernel that dynamic casts to the class true is returned, otherwise false.

    Discussion

    This function uses the OSMetaClass system in the kernel to determine if the object will dynamic cast to a class, specified as a C-string. In other words, if the object is of that class or a subclass.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Return the bundle identifier of the given class.

    Declaration

    Swift

    func IOObjectCopyBundleIdentifierForClass(_ classname: CFString!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef IOObjectCopyBundleIdentifierForClass ( CFStringRef classname );

    Parameters

    classname

    The name of the class as a CFString.

    Return Value

    The resulting CFStringRef. This should be released by the caller. If a valid class name is not passed in, then NULL is returned.

    Discussion

    This function uses the OSMetaClass system in the kernel to derive the name of the kmod, which is the same as the bundle identifier.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.4 and later.

  • Return the class name of an IOKit object.

    Declaration

    Swift

    func IOObjectCopyClass(_ object: io_object_t) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef IOObjectCopyClass ( io_object_t object );

    Parameters

    object

    The IOKit object.

    Return Value

    The resulting CFStringRef. This should be released by the caller. If a valid object is not passed in, then NULL is returned.

    Discussion

    This function does the same thing as IOObjectGetClass, but returns the result as a CFStringRef.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.4 and later.

  • Return the superclass name of the given class.

    Declaration

    Swift

    func IOObjectCopySuperclassForClass(_ classname: CFString!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef IOObjectCopySuperclassForClass ( CFStringRef classname );

    Parameters

    classname

    The name of the class as a CFString.

    Return Value

    The resulting CFStringRef. This should be released by the caller. If there is no superclass, or a valid class name is not passed in, then NULL is returned.

    Discussion

    This function uses the OSMetaClass system in the kernel to derive the name of the superclass of the class.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.4 and later.

  • Return the class name of an IOKit object.

    Declaration

    Swift

    func IOObjectGetClass(_ object: io_object_t, _ className: UnsafeMutablePointer<Int8>) -> kern_return_t

    Objective-C

    kern_return_t IOObjectGetClass ( io_object_t object, io_name_t className );

    Parameters

    object

    The IOKit object.

    className

    Caller allocated buffer to receive the name string.

    Return Value

    A kern_return_t error code.

    Discussion

    This function uses the OSMetaClass system in the kernel to derive the name of the class the object is an instance of.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns kernel retain count of an IOKit object.

    Declaration

    Swift

    func IOObjectGetKernelRetainCount(_ object: io_object_t) -> UInt32

    Objective-C

    uint32_t IOObjectGetKernelRetainCount ( io_object_t object );

    Parameters

    object

    An IOKit object.

    Return Value

    If the object handle is valid, the kernel objects retain count is returned, otherwise zero is returned.

    Discussion

    This function may be used in diagnostics to determine the current retain count of the kernel object at the kernel level.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.6 and later.

  • Returns kernel retain count of an IOKit object. Identical to IOObjectGetKernelRetainCount() but available prior to Mac OS 10.6.

    Declaration

    Swift

    func IOObjectGetRetainCount(_ object: io_object_t) -> UInt32

    Objective-C

    uint32_t IOObjectGetRetainCount ( io_object_t object );

    Parameters

    object

    An IOKit object.

    Return Value

    If the object handle is valid, the kernel objects retain count is returned, otherwise zero is returned.

    Discussion

    This function may be used in diagnostics to determine the current retain count of the kernel object at the kernel level.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the retain count for the current process of an IOKit object.

    Declaration

    Swift

    func IOObjectGetUserRetainCount(_ object: io_object_t) -> UInt32

    Objective-C

    uint32_t IOObjectGetUserRetainCount ( io_object_t object );

    Parameters

    object

    An IOKit object.

    Return Value

    If the object handle is valid, the objects user retain count is returned, otherwise zero is returned.

    Discussion

    This function may be used in diagnostics to determine the current retain count for the calling process of the kernel object.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.6 and later.

  • Checks two object handles to see if they represent the same kernel object.

    Declaration

    Swift

    func IOObjectIsEqualTo(_ object: io_object_t, _ anObject: io_object_t) -> boolean_t

    Objective-C

    boolean_t IOObjectIsEqualTo ( io_object_t object, io_object_t anObject );

    Parameters

    object

    An IOKit object.

    anObject

    Another IOKit object.

    Return Value

    If both object handles are valid, and represent the same object in the kernel true is returned, otherwise false.

    Discussion

    If two object handles are returned by IOKitLib functions, this function will compare them to see if they represent the same kernel object.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Releases an object handle previously returned by IOKitLib.

    Declaration

    Swift

    func IOObjectRelease(_ object: io_object_t) -> kern_return_t

    Objective-C

    kern_return_t IOObjectRelease ( io_object_t object );

    Parameters

    object

    The IOKit object to release.

    Return Value

    A kern_return_t error code.

    Discussion

    All objects returned by IOKitLib should be released with this function when access to them is no longer needed. Using the object after it has been released may or may not return an error, depending on how many references the task has to the same object in the kernel.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Retains an object handle previously returned by IOKitLib.

    Declaration

    Swift

    func IOObjectRetain(_ object: io_object_t) -> kern_return_t

    Objective-C

    kern_return_t IOObjectRetain ( io_object_t object );

    Parameters

    object

    The IOKit object to retain.

    Return Value

    A kern_return_t error code.

    Discussion

    Gives the caller an additional reference to an existing object handle previously returned by IOKitLib.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.1 and later.

  • Create an iterator rooted at the registry root.

    Declaration

    Swift

    func IORegistryCreateIterator(_ masterPort: mach_port_t, _ plane: UnsafePointer<Int8>, _ options: IOOptionBits, _ iterator: UnsafeMutablePointer<io_iterator_t>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryCreateIterator ( mach_port_t masterPort, const io_name_t plane, IOOptionBits options, io_iterator_t *iterator );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    options

    kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator.

    iterator

    A created iterator handle, to be released by the caller when it has finished with it.

    Return Value

    A kern_return_t error code.

    Discussion

    This method creates an IORegistryIterator in the kernel that is set up with options to iterate children of the registry root entry, and to recurse automatically into entries as they are returned, or only when instructed with calls to IORegistryIteratorEnterEntry. The iterator object keeps track of entries that have been recursed into previously to avoid loops.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create a CF dictionary representation of a registry entry's property table.

    Declaration

    Swift

    func IORegistryEntryCreateCFProperties(_ entry: io_registry_entry_t, _ properties: UnsafeMutablePointer<Unmanaged<CFMutableDictionary>?>, _ allocator: CFAllocator!, _ options: IOOptionBits) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryCreateCFProperties ( io_registry_entry_t entry, CFMutableDictionaryRef *properties, CFAllocatorRef allocator, IOOptionBits options );

    Parameters

    entry

    The registry entry handle whose property table to copy.

    properties

    A CFDictionary is created and returned the caller on success. The caller should release with CFRelease.

    allocator

    The CF allocator to use when creating the CF containers.

    options

    No options are currently defined.

    Return Value

    A kern_return_t error code.

    Discussion

    This function creates an instantaneous snapshot of a registry entry's property table, creating a CFDictionary analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create a CF representation of a registry entry's property.

    Declaration

    Swift

    func IORegistryEntryCreateCFProperty(_ entry: io_registry_entry_t, _ key: CFString!, _ allocator: CFAllocator!, _ options: IOOptionBits) -> Unmanaged<AnyObject>!

    Objective-C

    CFTypeRef IORegistryEntryCreateCFProperty ( io_registry_entry_t entry, CFStringRef key, CFAllocatorRef allocator, IOOptionBits options );

    Parameters

    entry

    The registry entry handle whose property to copy.

    key

    A CFString specifying the property name.

    allocator

    The CF allocator to use when creating the CF container.

    options

    No options are currently defined.

    Return Value

    A CF container is created and returned the caller on success. The caller should release with CFRelease.

    Discussion

    This function creates an instantaneous snapshot of a registry entry property, creating a CF container analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create an iterator rooted at a given registry entry.

    Declaration

    Swift

    func IORegistryEntryCreateIterator(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ options: IOOptionBits, _ iterator: UnsafeMutablePointer<io_iterator_t>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryCreateIterator ( io_registry_entry_t entry, const io_name_t plane, IOOptionBits options, io_iterator_t *iterator );

    Parameters

    entry

    The root entry to begin the iteration at.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    options

    kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated.

    iterator

    A created iterator handle, to be released by the caller when it has finished with it.

    Return Value

    A kern_return_t error code.

    Discussion

    This method creates an IORegistryIterator in the kernel that is set up with options to iterate children or parents of a root entry, and to recurse automatically into entries as they are returned, or only when instructed with calls to IORegistryIteratorEnterEntry. The iterator object keeps track of entries that have been recursed into previously to avoid loops.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Looks up a registry entry by path.

    Declaration

    Swift

    func IORegistryEntryFromPath(_ masterPort: mach_port_t, _ path: UnsafePointer<Int8>) -> io_registry_entry_t

    Objective-C

    io_registry_entry_t IORegistryEntryFromPath ( mach_port_t masterPort, const io_string_t path );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    path

    A C-string path.

    Return Value

    A handle to the IORegistryEntry witch was found with the path, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure.

    Discussion

    This function parses paths to lookup registry entries. The path should begin with '<plane name>:' If there are characters remaining unparsed after an entry has been looked up, this is considered an invalid lookup. Paths are further documented in IORegistryEntry.h

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the first child of a registry entry in a plane.

    Declaration

    Swift

    func IORegistryEntryGetChildEntry(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ child: UnsafeMutablePointer<io_registry_entry_t>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetChildEntry ( io_registry_entry_t entry, const io_name_t plane, io_registry_entry_t *child );

    Parameters

    entry

    The registry entry whose child to look up.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    child

    The first child of the registry entry, on success. The child must be released by the caller.

    Return Value

    A kern_return_t error code.

    Discussion

    This function will return the child which first attached to a registry entry in a plane.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an iterator over an registry entry's child entries in a plane.

    Declaration

    Swift

    func IORegistryEntryGetChildIterator(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ iterator: UnsafeMutablePointer<io_iterator_t>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetChildIterator ( io_registry_entry_t entry, const io_name_t plane, io_iterator_t *iterator );

    Parameters

    entry

    The registry entry whose children to iterate over.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    iterator

    The created iterator over the children of the entry, on success. The iterator must be released when the iteration is finished.

    Return Value

    A kern_return_t error code.

    Discussion

    This method creates an iterator which will return each of a registry entry's child entries in a specified plane.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a C-string location assigned to a registry entry, in a specified plane.

    Declaration

    Swift

    func IORegistryEntryGetLocationInPlane(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ location: UnsafeMutablePointer<Int8>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetLocationInPlane ( io_registry_entry_t entry, const io_name_t plane, io_name_t location );

    Parameters

    entry

    The registry entry handle whose name to look up.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    location

    The caller's buffer to receive the location string.

    Return Value

    A kern_return_t error code.

    Discussion

    Registry entries can given a location string in a particular plane, or globally. If the entry has had a location set in the specified plane that location string will be returned, otherwise the global location string is returned. If no global location string has been set, an error is returned.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.1 and later.

  • Returns a C-string name assigned to a registry entry.

    Declaration

    Swift

    func IORegistryEntryGetName(_ entry: io_registry_entry_t, _ name: UnsafeMutablePointer<Int8>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetName ( io_registry_entry_t entry, io_name_t name );

    Parameters

    entry

    The registry entry handle whose name to look up.

    name

    The caller's buffer to receive the name.

    Return Value

    A kern_return_t error code.

    Discussion

    Registry entries can be named in a particular plane, or globally. This function returns the entry's global name. The global name defaults to the entry's meta class name if it has not been named.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a C-string name assigned to a registry entry, in a specified plane.

    Declaration

    Swift

    func IORegistryEntryGetNameInPlane(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ name: UnsafeMutablePointer<Int8>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetNameInPlane ( io_registry_entry_t entry, const io_name_t plane, io_name_t name );

    Parameters

    entry

    The registry entry handle whose name to look up.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    name

    The caller's buffer to receive the name.

    Return Value

    A kern_return_t error code.

    Discussion

    Registry entries can be named in a particular plane, or globally. This function returns the entry's name in the specified plane or global name if it has not been named in that plane. The global name defaults to the entry's meta class name if it has not been named.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the first parent of a registry entry in a plane.

    Declaration

    Swift

    func IORegistryEntryGetParentEntry(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ parent: UnsafeMutablePointer<io_registry_entry_t>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetParentEntry ( io_registry_entry_t entry, const io_name_t plane, io_registry_entry_t *parent );

    Parameters

    entry

    The registry entry whose parent to look up.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    parent

    The first parent of the registry entry, on success. The parent must be released by the caller.

    Return Value

    A kern_return_t error code.

    Discussion

    This function will return the parent to which the registry entry was first attached in a plane.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an iterator over an registry entry's parent entries in a plane.

    Declaration

    Swift

    func IORegistryEntryGetParentIterator(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ iterator: UnsafeMutablePointer<io_iterator_t>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetParentIterator ( io_registry_entry_t entry, const io_name_t plane, io_iterator_t *iterator );

    Parameters

    entry

    The registry entry whose parents to iterate over.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    iterator

    The created iterator over the parents of the entry, on success. The iterator must be released when the iteration is finished.

    Return Value

    A kern_return_t error.

    Discussion

    This method creates an iterator which will return each of a registry entry's parent entries in a specified plane.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create a path for a registry entry.

    Declaration

    Swift

    func IORegistryEntryGetPath(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ path: UnsafeMutablePointer<Int8>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetPath ( io_registry_entry_t entry, const io_name_t plane, io_string_t path );

    Parameters

    entry

    The registry entry handle whose path to look up.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    path

    A char buffer allocated by the caller.

    Return Value

    IORegistryEntryGetPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path.

    Discussion

    The path for a registry entry is copied to the caller's buffer. The path describes the entry's attachment in a particular plane, which must be specified. The path begins with the plane name followed by a colon, and then followed by '/' separated path components for each of the entries between the root and the registry entry. An alias may also exist for the entry, and will be returned if available.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an ID for the registry entry that is global to all tasks.

    Declaration

    Swift

    func IORegistryEntryGetRegistryEntryID(_ entry: io_registry_entry_t, _ entryID: UnsafeMutablePointer<UInt64>) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntryGetRegistryEntryID ( io_registry_entry_t entry, uint64_t *entryID );

    Parameters

    entry

    The registry entry handle whose ID to look up.

    entryID

    The resulting ID.

    Return Value

    A kern_return_t error code.

    Discussion

    The entry ID returned by IORegistryEntryGetRegistryEntryID can be used to identify a registry entry across all tasks. A registry entry may be looked up by its entryID by creating a matching dictionary with IORegistryEntryIDMatching() to be used with the IOKit matching functions. The ID is valid only until the machine reboots.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.6 and later.

  • Create a matching dictionary that specifies an IOService match based on a registry entry ID.

    Declaration

    Swift

    func IORegistryEntryIDMatching(_ entryID: UInt64) -> Unmanaged<CFMutableDictionary>!

    Objective-C

    CFMutableDictionaryRef IORegistryEntryIDMatching ( uint64_t entryID );

    Parameters

    entryID

    The registry entry ID to be found.

    Return Value

    The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller.

    Discussion

    This function creates a matching dictionary that will match a registered, active IOService found with the given registry entry ID. The entry ID for a registry entry is returned by IORegistryEntryGetRegistryEntryID().

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.6 and later.

  • Determines if the registry entry is attached in a plane.

    Declaration

    Swift

    func IORegistryEntryInPlane(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>) -> boolean_t

    Objective-C

    boolean_t IORegistryEntryInPlane ( io_registry_entry_t entry, const io_name_t plane );

    Parameters

    entry

    The registry entry.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    Return Value

    If the entry has a parent in the plane, true is returned, otherwise false is returned.

    Discussion

    This method determines if the entry is attached in a plane to any other entry.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create a CF representation of a registry entry's property.

    Declaration

    Swift

    func IORegistryEntrySearchCFProperty(_ entry: io_registry_entry_t, _ plane: UnsafePointer<Int8>, _ key: CFString!, _ allocator: CFAllocator!, _ options: IOOptionBits) -> AnyObject!

    Objective-C

    CFTypeRef IORegistryEntrySearchCFProperty ( io_registry_entry_t entry, const io_name_t plane, CFStringRef key, CFAllocatorRef allocator, IOOptionBits options );

    Parameters

    entry

    The registry entry at which to start the search.

    plane

    The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

    key

    A CFString specifying the property name.

    allocator

    The CF allocator to use when creating the CF container.

    options

    kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard IORegistryEntryCreateCFProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.

    Return Value

    A CF container is created and returned the caller on success. The caller should release with CFRelease.

    Discussion

    This function creates an instantaneous snapshot of a registry entry property, creating a CF container analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. This function will search for a property, starting first with specified registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the same semantics as IORegistryEntryCreateCFProperty. The iteration keeps track of entries that have been recursed into previously to avoid loops.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.1 and later.

  • Set CF container based properties in a registry entry.

    Declaration

    Swift

    func IORegistryEntrySetCFProperties(_ entry: io_registry_entry_t, _ properties: AnyObject!) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntrySetCFProperties ( io_registry_entry_t entry, CFTypeRef properties );

    Parameters

    entry

    The registry entry whose properties to set.

    properties

    A CF container - commonly a CFDictionary but this is not enforced. The container should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects.

    Return Value

    A kern_return_t error code returned by the object.

    Discussion

    This is a generic method to pass a CF container of properties to an object in the registry. Setting properties in a registry entry is not generally supported, it is more common to support IOConnectSetCFProperties for connection based property setting. The properties are interpreted by the object.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Set a CF container based property in a registry entry.

    Declaration

    Swift

    func IORegistryEntrySetCFProperty(_ entry: io_registry_entry_t, _ propertyName: CFString!, _ property: AnyObject!) -> kern_return_t

    Objective-C

    kern_return_t IORegistryEntrySetCFProperty ( io_registry_entry_t entry, CFStringRef propertyName, CFTypeRef property );

    Parameters

    entry

    The registry entry whose property to set.

    propertyName

    The name of the property as a CFString.

    property

    A CF container - should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects.

    Return Value

    A kern_return_t error code returned by the object.

    Discussion

    This is a generic method to pass a CF container as a property to an object in the registry. Setting properties in a registry entry is not generally supported, it is more common to support IOConnectSetCFProperty for connection based property setting. The property is interpreted by the object.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Return a handle to the registry root.

    Declaration

    Swift

    func IORegistryGetRootEntry(_ masterPort: mach_port_t) -> io_registry_entry_t

    Objective-C

    io_registry_entry_t IORegistryGetRootEntry ( mach_port_t masterPort );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    Return Value

    A handle to the IORegistryEntry root instance, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure.

    Discussion

    This method provides an accessor to the root of the registry for the machine. The root may be passed to a registry iterator when iterating a plane, and contains properties that describe the available planes, and diagnostic information for IOKit.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Recurse into the current entry in the registry iteration.

    Declaration

    Swift

    func IORegistryIteratorEnterEntry(_ iterator: io_iterator_t) -> kern_return_t

    Objective-C

    kern_return_t IORegistryIteratorEnterEntry ( io_iterator_t iterator );

    Return Value

    A kern_return_t error code.

    Discussion

    This method makes the current entry, ie. the last entry returned by IOIteratorNext, the root in a new level of recursion.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Exits a level of recursion, restoring the current entry.

    Declaration

    Swift

    func IORegistryIteratorExitEntry(_ iterator: io_iterator_t) -> kern_return_t

    Objective-C

    kern_return_t IORegistryIteratorExitEntry ( io_iterator_t iterator );

    Return Value

    kIOReturnSuccess if a level of recursion was undone, kIOReturnNoDevice if no recursive levels are left in the iteration.

    Discussion

    This method undoes an IORegistryIteratorEnterEntry, restoring the current entry. If there are no more levels of recursion to exit false is returned, otherwise true is returned.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Register for notification of state changes in an IOService.

    Declaration

    Swift

    func IOServiceAddInterestNotification(_ notifyPort: IONotificationPort!, _ service: io_service_t, _ interestType: UnsafePointer<Int8>, _ callback: IOServiceInterestCallback, _ refCon: UnsafeMutablePointer<Void>, _ notification: UnsafeMutablePointer<io_object_t>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceAddInterestNotification ( IONotificationPortRef notifyPort, io_service_t service, const io_name_t interestType, IOServiceInterestCallback callback, void *refCon, io_object_t *notification );

    Parameters

    notifyPort

    A IONotificationPortRef object that controls how messages will be sent when the notification is fired. See IONotificationPortCreate.

    interestType

    A notification type from IOKitKeys.h

    kIOGeneralInterest General state changes delivered via the IOService::message API.

    kIOBusyInterest Delivered when the IOService changes its busy state to or from zero. The message argument contains the new busy state causing the notification.

    callback

    A callback function called when the notification fires, with messageType and messageArgument for the state change.

    refCon

    A reference constant for the callbacks use.

    notification

    An object handle is returned on success, and should be released by the caller when the notification is to be destroyed.

    Return Value

    A kern_return_t error code.

    Discussion

    IOService objects deliver notifications of their state changes to their clients via the IOService::message API, and to other interested parties including callers of this function. Message type s are defined IOKit/IOMessage.h.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Look up registered IOService objects that match a matching dictionary, and install a notification request of new IOServices that match.

    Declaration

    Swift

    func IOServiceAddMatchingNotification(_ notifyPort: IONotificationPort!, _ notificationType: UnsafePointer<Int8>, _ matching: CFDictionary!, _ callback: IOServiceMatchingCallback, _ refCon: UnsafeMutablePointer<Void>, _ notification: UnsafeMutablePointer<io_iterator_t>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceAddMatchingNotification ( IONotificationPortRef notifyPort, const io_name_t notificationType, CFDictionaryRef matching, IOServiceMatchingCallback callback, void *refCon, io_iterator_t *notification );

    Parameters

    notifyPort

    A IONotificationPortRef object that controls how messages will be sent when the armed notification is fired. When the notification is delivered, the io_iterator_t representing the notification should be iterated through to pick up all outstanding objects. When the iteration is finished the notification is rearmed. See IONotificationPortCreate.

    notificationType

    A notification type from IOKitKeys.h

    kIOPublishNotification Delivered when an IOService is registered.

    kIOFirstPublishNotification Delivered when an IOService is registered, but only once per IOService instance. Some IOService's may be reregistered when their state is changed.

    kIOMatchedNotification Delivered when an IOService has had all matching drivers in the kernel probed and started.

    kIOFirstMatchNotification Delivered when an IOService has had all matching drivers in the kernel probed and started, but only once per IOService instance. Some IOService's may be reregistered when their state is changed.

    kIOTerminatedNotification Delivered after an IOService has been terminated.

    matching

    A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.

    callback

    A callback function called when the notification fires.

    refCon

    A reference constant for the callbacks use.

    notification

    An iterator handle is returned on success, and should be released by the caller when the notification is to be destroyed. The notification is armed when the iterator is emptied by calls to IOIteratorNext - when no more objects are returned, the notification is armed. Note the notification is not armed when first created.

    Return Value

    A kern_return_t error code.

    Discussion

    This is the preferred method of finding IOService objects that may arrive at any time. The type of notification specifies the state change the caller is interested in, on IOService's that match the match dictionary. Notification types are identified by name, and are defined in IOKitKeys.h. The matching information used in the matching dictionary may vary depending on the class of service being looked up.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Close a connection to an IOService and destroy the connect handle.

    Declaration

    Swift

    func IOServiceClose(_ connect: io_connect_t) -> kern_return_t

    Objective-C

    kern_return_t IOServiceClose ( io_connect_t connect );

    Parameters

    connect

    The connect handle created by IOServiceOpen. It will be destroyed by this function, and should not be released with IOObjectRelease.

    Return Value

    A kern_return_t error code.

    Discussion

    A connection created with the IOServiceOpen should be closed when the connection is no longer to be used with IOServiceClose.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the busyState of an IOService.

    Declaration

    Swift

    func IOServiceGetBusyState(_ service: io_service_t, _ busyState: UnsafeMutablePointer<UInt32>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceGetBusyState ( io_service_t service, uint32_t *busyState );

    Parameters

    service

    The IOService whose busyState to return.

    busyState

    The busyState count is returned.

    Return Value

    A kern_return_t error code.

    Discussion

    Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService, its busyState is increased by one. Change in busyState to or from zero also changes the IOService's provider's busyState by one, which means that an IOService is marked busy when any of the above activities is ocurring on it or any of its clients.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Look up a registered IOService object that matches a matching dictionary.

    Declaration

    Swift

    func IOServiceGetMatchingService(_ masterPort: mach_port_t, _ matching: CFDictionary!) -> io_service_t

    Objective-C

    io_service_t IOServiceGetMatchingService ( mach_port_t masterPort, CFDictionaryRef matching );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    matching

    A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.

    Return Value

    The first service matched is returned on success. The service must be released by the caller.

    Discussion

    This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.2 and later.

  • Look up registered IOService objects that match a matching dictionary.

    Declaration

    Swift

    func IOServiceGetMatchingServices(_ masterPort: mach_port_t, _ matching: CFDictionary!, _ existing: UnsafeMutablePointer<io_iterator_t>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceGetMatchingServices ( mach_port_t masterPort, CFDictionaryRef matching, io_iterator_t *existing );

    Parameters

    masterPort

    The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

    matching

    A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.

    existing

    An iterator handle is returned on success, and should be released by the caller when the iteration is finished.

    Return Value

    A kern_return_t error code.

    Discussion

    This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create a matching dictionary that specifies an IOService class match.

    Declaration

    Swift

    func IOServiceMatching(_ name: UnsafePointer<Int8>) -> Unmanaged<CFMutableDictionary>!

    Objective-C

    CFMutableDictionaryRef IOServiceMatching ( const char *name );

    Parameters

    name

    The class name, as a const C-string. Class matching is successful on IOService's of this class or any subclass.

    Return Value

    The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller.

    Discussion

    A very common matching criteria for IOService is based on its class. IOServiceMatching will create a matching dictionary that specifies any IOService of a class, or its subclasses. The class is specified by C-string name.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Match an IOService objects with matching dictionary.

    Declaration

    Swift

    func IOServiceMatchPropertyTable(_ service: io_service_t, _ matching: CFDictionary!, _ matches: UnsafeMutablePointer<boolean_t>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceMatchPropertyTable ( io_service_t service, CFDictionaryRef matching, boolean_t *matches );

    Parameters

    service

    The IOService object to match.

    matching

    A CF dictionary containing matching information. IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.

    matches

    The boolean result is returned.

    Return Value

    A kern_return_t error code.

    Discussion

    This function calls the matching method of an IOService object and returns the boolean result.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Create a matching dictionary that specifies an IOService name match.

    Declaration

    Swift

    func IOServiceNameMatching(_ name: UnsafePointer<Int8>) -> Unmanaged<CFMutableDictionary>!

    Objective-C

    CFMutableDictionaryRef IOServiceNameMatching ( const char *name );

    Parameters

    name

    The IOService name, as a const C-string.

    Return Value

    The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller.

    Discussion

    A common matching criteria for IOService is based on its name. IOServiceNameMatching will create a matching dictionary that specifies an IOService with a given name. Some IOServices created from the device tree will perform name matching on the standard compatible, name, model properties.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • A request to create a connection to an IOService.

    Declaration

    Swift

    func IOServiceOpen(_ service: io_service_t, _ owningTask: task_port_t, _ type: UInt32, _ connect: UnsafeMutablePointer<io_connect_t>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceOpen ( io_service_t service, task_port_t owningTask, uint32_t type, io_connect_t *connect );

    Parameters

    service

    The IOService object to open a connection to, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs.

    owningTask

    The mach task requesting the connection.

    type

    A constant specifying the type of connection to be created, interpreted only by the IOService's family.

    connect

    An io_connect_t handle is returned on success, to be used with the IOConnectXXX APIs. It should be destroyed with IOServiceClose().

    Return Value

    A return code generated by IOService::newUserClient.

    Discussion

    A non kernel client may request a connection be opened via the IOServiceOpen() library function, which will call IOService::newUserClient in the kernel. The rules & capabilities of user level clients are family dependent, the default IOService implementation returns kIOReturnUnsupported.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • A request to rescan a bus for device changes.

    Declaration

    Swift

    func IOServiceRequestProbe(_ service: io_service_t, _ options: UInt32) -> kern_return_t

    Objective-C

    kern_return_t IOServiceRequestProbe ( io_service_t service, uint32_t options );

    Parameters

    service

    The IOService object to request a rescan, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs.

    options

    An options mask, interpreted only by the IOService's family.

    Return Value

    A return code generated by IOService::requestProbe.

    Discussion

    A non kernel client may request a bus or controller rescan for added or removed devices, if the bus family does automatically notice such changes. For example, SCSI bus controllers do not notice device changes. The implementation of this routine is family dependent, and the default IOService implementation returns kIOReturnUnsupported.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Wait for an IOService's busyState to be zero.

    Declaration

    Swift

    func IOServiceWaitQuiet(_ service: io_service_t, _ waitTime: UnsafeMutablePointer<mach_timespec_t>) -> kern_return_t

    Objective-C

    kern_return_t IOServiceWaitQuiet ( io_service_t service, mach_timespec_t *waitTime );

    Parameters

    service

    The IOService wait on.

    waitTime

    Specifies a maximum time to wait.

    Return Value

    Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess.

    Discussion

    Blocks the caller until an IOService is non busy, see IOServiceGetBusyState.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

Callbacks

  • standard callback function for asynchronous I/O requests with lots of extra arguments beyond a refcon and result code.

    Declaration

    Swift

    typealias IOAsyncCallback = CFunctionPointer<((UnsafeMutablePointer<Void>, IOReturn, UnsafeMutablePointer<UnsafeMutablePointer<Void>>, UInt32) -> Void)>

    Objective-C

    typedef void ( *IOAsyncCallback)( void *refcon, IOReturn result, void **args, uint32_t numArgs);

    Parameters

    refcon

    The refcon passed into the original I/O request

    result

    The result of the I/O operation

    args

    Array of extra arguments

    numArgs

    Number of extra arguments

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • standard callback function for asynchronous I/O requests with no extra arguments beyond a refcon and result code.

    Declaration

    Swift

    typealias IOAsyncCallback0 = CFunctionPointer<((UnsafeMutablePointer<Void>, IOReturn) -> Void)>

    Objective-C

    typedef void ( *IOAsyncCallback0)( void *refcon, IOReturn result);

    Parameters

    refcon

    The refcon passed into the original I/O request

    result

    The result of the I/O operation

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • standard callback function for asynchronous I/O requests with one extra argument beyond a refcon and result code. This is often a count of the number of bytes transferred

    Declaration

    Swift

    typealias IOAsyncCallback1 = CFunctionPointer<((UnsafeMutablePointer<Void>, IOReturn, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void ( *IOAsyncCallback1)( void *refcon, IOReturn result, void *arg0);

    Parameters

    refcon

    The refcon passed into the original I/O request

    result

    The result of the I/O operation

    arg0

    Extra argument

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • standard callback function for asynchronous I/O requests with two extra arguments beyond a refcon and result code.

    Declaration

    Swift

    typealias IOAsyncCallback2 = CFunctionPointer<((UnsafeMutablePointer<Void>, IOReturn, UnsafeMutablePointer<Void>, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void ( *IOAsyncCallback2)( void *refcon, IOReturn result, void *arg0, void *arg1);

    Parameters

    refcon

    The refcon passed into the original I/O request

    result

    The result of the I/O operation

    arg0

    Extra argument

    arg1

    Extra argument

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Callback function to be notified of changes in state of an IOService.

    Declaration

    Swift

    typealias IOServiceInterestCallback = CFunctionPointer<((UnsafeMutablePointer<Void>, io_service_t, UInt32, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void ( *IOServiceInterestCallback)( void *refcon, io_service_t service, uint32_t messageType, void *messageArgument );

    Parameters

    refcon

    The refcon passed when the notification was installed.

    service

    The IOService whose state has changed.

    messageType

    A messageType enum, defined by IOKit/IOMessage.h or by the IOService's family.

    messageArgument

    An argument for the message, dependent on the messageType. If the message data is larger than sizeof(void*), then messageArgument contains a pointer to the message data; otherwise, messageArgument contains the message data.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

  • Callback function to be notified of IOService publication.

    Declaration

    Swift

    typealias IOServiceMatchingCallback = CFunctionPointer<((UnsafeMutablePointer<Void>, io_iterator_t) -> Void)>

    Objective-C

    typedef void ( *IOServiceMatchingCallback)( void *refcon, io_iterator_t iterator );

    Parameters

    refcon

    The refcon passed when the notification was installed.

    iterator

    The notification iterator which now has new objects.

    Import Statement

    Objective-C

    @import IOKit;

    Swift

    import IOKit

    Availability

    Available in OS X v10.0 and later.

Constants

See the Overview for header-level documentation.

  • Declaration

    Swift

    let kIOMasterPortDefault: mach_port_t

    Objective-C

    extern const mach_port_t kIOMasterPortDefault;

    Constants

    • kIOMasterPortDefault

      kIOMasterPortDefault

      The default mach port used to initiate communication with IOKit.

      When specifying a master port to IOKit functions, the NULL argument indicates "use the default". This is a synonym for NULL, if you'd rather use a named constant.

      Available in OS X v10.2 and later.