IOKitLib.h



Functions

IOBSDNameMatching

Abstract: Create a matching dictionary that specifies an IOService match based on BSD device name.
CFMutableDictionaryRef IOBSDNameMatching(
 mach_port_t masterPort,
 unsigned int options,
 const char * bsdName );

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.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
optionsNo options are currently defined.
bsdNameThe BSD name, as a const char *.
Result: 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.

IOConnectAddClient

Abstract: Inform a connection of a second connection.
kern_return_t IOConnectAddClient(
 io_connect_t connect,
 io_connect_t client );

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

Parameters

NameDescription
connectThe connect handle created by IOServiceOpen.
clientAnother connect handle created by IOServiceOpen.
Result: A kern_return_t error code returned by the family.

IOConnectGetService

Abstract: Returns the IOService a connect handle was opened on.
kern_return_t IOConnectGetService(
 io_connect_t connect,
 io_service_t * service );

Finds the service object a connection was opened on.

Parameters

NameDescription
connectThe connect handle created by IOServiceOpen.
serviceOn succes, the service handle the connection was opened on, which should be released with IOObjectRelease.
Result: A kern_return_t error code.

IOConnectMapMemory

Abstract: Map hardware or shared memory into the caller's task.
kern_return_t IOConnectMapMemory(
 io_connect_t connect,
 unsigned int memoryType,
 task_port_t intoTask,
 vm_address_t * atAddress,
 vm_size_t * ofSize,
 IOOptionBits options );

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.

Parameters

NameDescription
connectThe connect handle created by IOServiceOpen.
memoryTypeWhat is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings.
intoTaskThe task port for the task in which to create the mapping. This may be different to the task which the opened the connection.
atAddressAn 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.
ofSizeThe size of the mapping created is passed back on success.
Result: A kern_return_t error code.

IOConnectSetCFProperties

Abstract: Set CF container based properties on a connection.
kern_return_t IOConnectSetCFProperties(
 io_connect_t connect,
 CFTypeRef properties );

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.

Parameters

NameDescription
connectThe connect handle created by IOServiceOpen.
propertiesA 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.
Result: A kern_return_t error code returned by the family.

IOConnectSetNotificationPort

Abstract: Set a port to receive family specific notifications.
kern_return_t IOConnectSetNotificationPort(
 io_connect_t connect,
 unsigned int type,
 mach_port_t port,
 unsigned int reference );

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

Parameters

NameDescription
connectThe connect handle created by IOServiceOpen.
typeThe type of notification requested, not interpreted by IOKit and family defined.
portThe port to which to send notifications.
referenceSome families may support passing a reference parameter for the callers use with the notification.
Result: A kern_return_t error code.

IOCreateReceivePort

Abstract: Creates and returns a mach port suitable for receiving IOKit messages of the specified type.
kern_return_t IOCreateReceivePort( int msgType, mach_port_t * recvPort );

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.

Parameters

NameDescription
msgTypeType of message to be sent to this port (kOSNotificationMessageID or kOSAsyncCompleteMessageID)
recvPortThe created port is returned.
Result: A kern_return_t error code.

IOIteratorIsValid

Abstract: Checks an iterator is still valid.
boolean_t IOIteratorIsValid(
 io_iterator_t iterator );

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.

Parameters

NameDescription
iteratorAn IOKit iterator handle.
Result: True if the iterator handle is valid, otherwise false is returned.

IOIteratorNext

Abstract: Returns the next object in an iteration.
io_object_t IOIteratorNext(
 io_iterator_t iterator );

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

Parameters

NameDescription
iteratorAn IOKit iterator handle.
Result: If the iterator handle is valid, the next element in the iteration is returned, otherwise zero is returned.

IOIteratorReset

Abstract: Resets an iteration back to the beginning.
void IOIteratorReset(
 io_iterator_t iterator );

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

Parameters

NameDescription
iteratorAn IOKit iterator handle.

IOKitGetBusyState

Abstract: Returns the busyState of all IOServices.
kern_return_t IOKitGetBusyState(
 mach_port_t masterPort,
 int * busyState );

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.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
busyStateThe busyState count is returned.
Result: A kern_return_t error code.

IOKitWaitQuiet

Abstract: Wait for a all IOServices' busyState to be zero.
kern_return_t IOKitWaitQuiet(
 mach_port_t masterPort,
 mach_timespec_t * waitTime );

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

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
waitTimeSpecifies a maximum time to wait.
Result: Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess.

IOMasterPort

Abstract: Returns the mach port used to initiate communication with IOKit.
kern_return_t IOMasterPort( mach_port_t bootstrapPort,
 mach_port_t * masterPort );

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

Parameters

NameDescription
sizeThe task's bootstrap port, pass bootstrap_port from mach/mach_init.h.
masterPortThe master port is returned.
Result: A kern_return_t error code.

IOObjectConformsTo

Abstract: Performs an OSDynamicCast operation on an IOKit object.
boolean_t IOObjectConformsTo(
 io_object_t object,
 const io_name_t className );

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.

Parameters

NameDescription
objectAn IOKit object.
classNameThe name of the class, as a C-string.
Result: If the object handle is valid, and represents an object in the kernel that dynamic casts to the class true is returned, otherwise false.

IOObjectGetClass

Abstract: Return the class name of an IOKit object.
kern_return_t IOObjectGetClass(
 io_object_t object,
 io_name_t className );

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

Parameters

NameDescription
objectThe IOKit object.
classNameCaller allocated buffer to receive the name string.
Result: A kern_return_t error code.

IOObjectGetRetainCount

Abstract: Returns kernel retain count of an IOKit object.
int IOObjectGetRetainCount(
 io_object_t object );

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

Parameters

NameDescription
objectAn IOKit object.
Result: If the object handle is valid, the kernel objects retain count is returned, otherwise zero is returned.

IOObjectIsEqualTo

Abstract: Checks two object handles to see if they represent the same kernel object.
boolean_t IOObjectIsEqualTo(
 io_object_t object,
 io_object_t anObject );

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

Parameters

NameDescription
objectAn IOKit object.
anObjectAnother IOKit object.
Result: If both object handles are valid, and represent the same object in the kernel true is returned, otherwise false.

IOObjectRelease

Abstract: Releases an object handle previuous return by IOKitLib.
kern_return_t IOObjectRelease(
 io_object_t object );

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.

Parameters

NameDescription
objectThe IOKit object to release.
Result: A kern_return_t error code.

IOOpenFirmwarePathMatching

Abstract: Create a matching dictionary that specifies an IOService match based on an OpenFirmware device path.
CFMutableDictionaryRef IOOpenFirmwarePathMatching(
 mach_port_t masterPort,
 unsigned int options,
 const char * path );

Certain IOServices (currently, block and ethernet boot devices) may be looked up by a path that specifies their location in the OpenFirmware device tree, represented in the registry by the kIODeviceTreePlane plane. This function creates a matching dictionary that will match IOService's found with a given OpenFirmware device path.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
optionsNo options are currently defined.
pathThe OpenFirmware device path, as a const char *.
Result: 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.

IORegistryCreateIterator

Abstract: Create an iterator rooted at the registry root.
kern_return_t IORegistryCreateIterator(
 mach_port_t masterPort,
 const io_name_t plane,
 IOOptionBits options,
 io_iterator_t * iterator );

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.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
optionskIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator.
iteratorA created iterator handle, to be released by the caller when it has finished with it.
Result: A kern_return_t error code.

IORegistryEntryCreateCFProperties

Abstract: Create a CF dictionary representation of a registry entry's property table.
kern_return_t IORegistryEntryCreateCFProperties(
 io_registry_entry_t entry,
 CFMutableDictionaryRef * properties,
 CFAllocatorRef allocator,
 IOOptionBits options );

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.

Parameters

NameDescription
entryThe registry entry handle whose property table to copy.
propertiesA CFDictionary is created and returned the caller on success. The caller should release with CFRelease.
allocatorThe CF allocator to use when creating the CF containers.
optionsNo options are currently defined.
Result: A kern_return_t error code.

IORegistryEntryCreateIterator

Abstract: Create an iterator rooted at a given registry entry.
kern_return_t IORegistryEntryCreateIterator(
 io_registry_entry_t entry,
 const io_name_t plane,
 IOOptionBits options,
 io_iterator_t * iterator );

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.

Parameters

NameDescription
entryThe root entry to begin the iteration at.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
optionskIORegistryIterateRecursively 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.
iteratorA created iterator handle, to be released by the caller when it has finished with it.
Result: A kern_return_t error code.

IORegistryEntryFromPath

Abstract: Looks up a registry entry by path.
io_registry_entry_t IORegistryEntryFromPath(
 mach_port_t masterPort,
 const io_string_t path );

This function parses paths to lookup registry entries. The path should begin with ':' 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

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
pathA C-string path.
Result: 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.

IORegistryEntryGetChildEntry

Abstract: Returns the first child of a registry entry in a plane.
kern_return_t IORegistryEntryGetChildEntry(
 io_registry_entry_t entry,
 const io_name_t plane,
 io_registry_entry_t * child );

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

Parameters

NameDescription
entryThe registry entry whose child to look up.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
childThe first child of the registry entry, on success. The child must be released by the caller.
Result: A kern_return_t error code.

IORegistryEntryGetChildIterator

Abstract: Returns an iterator over an registry entry's child entries in a plane.
kern_return_t IORegistryEntryGetChildIterator(
 io_registry_entry_t entry,
 const io_name_t plane,
 io_iterator_t * iterator );

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

Parameters

NameDescription
entryThe registry entry whose children to iterate over.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
iteratorThe created iterator over the children of the entry, on success. The iterator must be released when the iteration is finished.
Result: A kern_return_t error code.

IORegistryEntryGetName

Abstract: Returns a C-string name assigned to a registry entry.
kern_return_t IORegistryEntryGetName(
 io_registry_entry_t entry,
 io_name_t name );

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.

Parameters

NameDescription
entryThe registry entry handle whose name to look up.
nameThe caller's buffer to receive the name.
Result: A kern_return_t error code.

IORegistryEntryGetNameInPlane

Abstract: Returns a C-string name assigned to a registry entry, in a specified plane.
kern_return_t IORegistryEntryGetNameInPlane(
 io_registry_entry_t entry,
 const io_name_t plane,
 io_name_t name );

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.

Parameters

NameDescription
entryThe registry entry handle whose name to look up.
nameThe caller's buffer to receive the name.
Result: A kern_return_t error code.

IORegistryEntryGetParentEntry

Abstract: Returns the first parent of a registry entry in a plane.
kern_return_t IORegistryEntryGetParentEntry(
 io_registry_entry_t entry,
 const io_name_t plane,
 io_registry_entry_t * parent );

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

Parameters

NameDescription
entryThe registry entry whose parent to look up.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
childThe first parent of the registry entry, on success. The parent must be released by the caller.
Result: A kern_return_t error code.

IORegistryEntryGetParentIterator

Abstract: Returns an iterator over an registry entry's parent entries in a plane.
kern_return_t IORegistryEntryGetParentIterator(
 io_registry_entry_t entry,
 const io_name_t plane,
 io_iterator_t * iterator );

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

Parameters

NameDescription
entryThe registry entry whose parents to iterate over.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
iteratorThe created iterator over the parents of the entry, on success. The iterator must be released when the iteration is finished.
Result: A kern_return_t error.

IORegistryEntryGetPath

Abstract: Create a path for a registry entry.
kern_return_t IORegistryEntryGetPath(
 io_registry_entry_t entry,
 const io_name_t plane,
 io_string_t path );

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.

Parameters

NameDescription
entryThe registry entry handle whose path to look up.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
pathA char buffer allocated by the caller.
Result: IORegistryEntryGetPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path.

IORegistryEntryGetProperty

Abstract: Copy a binary representation of one property from a registry entry.
kern_return_t IORegistryEntryGetProperty(
 io_registry_entry_t entry,
 const io_name_t propertyName,
 io_struct_inband_t buffer,
 unsigned int * size );

This function has limited use to retrieve a binary copy of simple property values without using CF containers. Currently, only OSData, OSString (& OSSymbol), OSNumber & OSBoolean properties are retrievable with IORegistryEntryGetProperty, and the size is limited to that of io_struct_inband_t (4096 bytes).

Parameters

NameDescription
entryThe registry entry handle whose property table read one property.
propertyNameThe name of the property in the registry entry's property table as a C-string.
bufferThe caller's buffer to receive the binary representation of the property if it exists.
sizeThe size of the property copied is returned.
Result: A kern_return_t error code.

IORegistryEntryInPlane

Abstract: Determines if the registry entry is attached in a plane.
boolean_t IORegistryEntryInPlane(
 io_registry_entry_t entry,
 const io_name_t plane );

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

Parameters

NameDescription
entryThe registry entry.
planeThe name of an existing registry plane. Plane names are defined in IOKitKeys, eg. kIOServicePlane.
Result: If the entry has a parent in the plane, true is returned, otherwise false is returned.

IORegistryEntrySetCFProperties

Abstract: Set CF container based properties in a registry entry.
kern_return_t IORegistryEntrySetCFProperties(
 io_registry_entry_t entry,
 CFTypeRef properties );

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.

Parameters

NameDescription
entryThe registry entry whose properties to set.
propertiesA 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.
Result: A kern_return_t error code returned by the object.

IORegistryGetRootEntry

Abstract: Return a handle to the registry root.
io_registry_entry_t IORegistryGetRootEntry(
 mach_port_t masterPort );

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.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
Result: A handle to the IORegistryEntry root instance, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure.

IORegistryIteratorEnterEntry

Abstract: Recurse into the current entry in the registry iteration.
kern_return_t IORegistryIteratorEnterEntry(
 io_iterator_t iterator );

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

Result: A kern_return_t error code.

IORegistryIteratorExitEntry

Abstract: Exits a level of recursion, restoring the current entry.
kern_return_t IORegistryIteratorExitEntry(
 io_iterator_t iterator );

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.

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

IOServiceAddNotification

Abstract: Look up registered IOService objects that match a matching dictionary, and install a notification request of new IOServices that match.
kern_return_t IOServiceAddNotification(
 mach_port_t masterPort,
 const io_name_t notificationType,
 CFDictionaryRef matching,
 mach_port_t wakePort,
 int reference,
 io_iterator_t * notification );

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.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
notificationTypeA 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.
matchingA CF dictionary containing matching information, of which one reference is consumed by this function. IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOOpenFirmwarePathMatching.
wakePortA port to which 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.
notificationAn 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.
Result: A kern_return_t error code.

IOServiceClose

Abstract: Close a connection to an IOService and destroy the connect handle.
kern_return_t IOServiceClose(
 io_connect_t connect );

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

Parameters

NameDescription
connectThe connect handle created by IOServiceOpen. It will be destroyed by this function, and should not be released with IOObjectRelease.
Result: A kern_return_t error code.

IOServiceGetBusyState

Abstract: Returns the busyState of an IOService.
kern_return_t IOServiceGetBusyState(
 io_service_t service,
 int * busyState );

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.

Parameters

NameDescription
serviceThe IOService whose busyState to return.
busyStateThe busyState count is returned.
Result: A kern_return_t error code.

IOServiceGetMatchingServices

Abstract: Look up registered IOService objects that match a matching dictionary.
kern_return_t IOServiceGetMatchingServices(
 mach_port_t masterPort,
 CFDictionaryRef matching,
 io_iterator_t * existing );

This is the preferred method of finding IOService objects currently registered by IOKit. IOServiceAddNotification 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.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
matchingA CF dictionary containing matching information, of which one reference is consumed by this function. IOKitLib can contruct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOOpenFirmwarePathMatching.
existingAn iterator handle is returned on success, and should be released by the caller when the iteration is finished.
Result: A kern_return_t error code.

IOServiceMatching

Abstract: Create a matching dictionary that specifies an IOService class match.
CFMutableDictionaryRef IOServiceMatching(
 const char * name );

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.

Parameters

NameDescription
nameThe class name, as a const C-string. Class matching is successful on IOService's of this class or any subclass.
Result: 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.

IOServiceNameMatching

Abstract: Create a matching dictionary that specifies an IOService name match.
CFMutableDictionaryRef IOServiceNameMatching(
 const char * name );

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 OpenFirmware device tree will perform name matching on the standard OF compatible, name, model properties.

Parameters

NameDescription
nameThe IOService name, as a const C-string.
Result: 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.

IOServiceOFPathToBSDName

Abstract: Utility to look up an IOService from its OpenFirmware device path, and return its BSD device name if available.
kern_return_t IOServiceOFPathToBSDName(mach_port_t masterPort,
 const io_name_t openFirmwarePath,
 io_name_t bsdName);

Certain IOServices (currently, block and ethernet boot devices) may be looked up by a path that specifies their location in the OpenFirmware device tree, represented in the registry by the kIODeviceTreePlane plane. This function looks up an IOService object with a given OpenFirmware device path, and returns its associated BSD device name.

Parameters

NameDescription
masterPortThe master port obtained from IOMasterPort().
openFirmwarePathThe OpenFirmware device path, as a const char *.
bsdNameThe BSD name, as a const char *, is copied to the callers buffer.
Result: A kern_return_t error code.

IOServiceOpen

Abstract: A request to create a connection to an IOService.
kern_return_t IOServiceOpen(
 io_service_t service,
 task_port_t owningTask,
 unsigned int type,
 io_connect_t * connect );

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.

Parameters

NameDescription
serviceThe IOService object to open a connection to, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs.
owningTaskThe mach task requesting the connection.
typeA constant specifying the type of connection to be created, interpreted only by the IOService's family.
connectAn io_connect_t handle is returned on success, to be used with the IOConnectXXX APIs. It should be destroyed with IOServiceClose().
Result: A return code generated by IOService::newUserClient.

IOServiceWaitQuiet

Abstract: Wait for an IOService's busyState to be zero.
kern_return_t IOServiceWaitQuiet(
 io_service_t service,
 mach_timespec_t * waitTime );

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

Parameters

NameDescription
serviceThe IOService wait on.
waitTimeSpecifies a maximum time to wait.
Result: Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess.

Typedefs

IOAsyncCallback

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

Parameters

NameDescription
refconThe refcon passed into the original I/O request
resultThe result of the I/O operation
argsArray of extra arguments
numArgsNumber of extra arguments

IOAsyncCallback0

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

Parameters

NameDescription
refconThe refcon passed into the original I/O request
resultThe result of the I/O operation

IOAsyncCallback1

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

Parameters

NameDescription
refconThe refcon passed into the original I/O request
resultThe result of the I/O operation
arg0Extra argument

IOAsyncCallback2

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

Parameters

NameDescription
refconThe refcon passed into the original I/O request
resultThe result of the I/O operation
arg0Extra argument
arg1Extra argument

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)