Objective-C Runtime

Describes the macOS Objective-C 2.0 runtime library support functions and data structures.

Overview

The Objective-C runtime is a runtime library that provides support for the dynamic properties of the Objective-C language, and as such is linked to by all Objective-C apps. Objective-C runtime library support functions are implemented in the shared library found at /usr/lib/libobjc.A.dylib.

You typically don't need to use the Objective-C runtime library directly when programming in Objective-C. This API is useful primarily for developing bridge layers between Objective-C and other languages, or for low-level debugging.

The macOS implementation of the Objective-C runtime library is unique to the Mac. For other platforms, the GNU Compiler Collection provides a different implementation with a similar API. This document covers only the macOS implementation.

The low-level Objective-C runtime API is significantly updated in OS X version 10.5. Many functions and all existing data structures are replaced with new functions. The old functions and structures are deprecated in 32-bit and absent in 64-bit mode. The API constrains several values to 32-bit ints even in 64-bit mode—class count, protocol count, methods per class, ivars per class, arguments per method, sizeof(all arguments) per method, and class version number. In addition, the new Objective-C ABI (not described here) further constrains sizeof(anInstance) to 32 bits, and three other values to 24 bits—methods per class, ivars per class, and sizeof(a single ivar). Finally, the obsolete NXHashTable and NXMapTable are limited to 4 billion items.

“Deprecated” below means “deprecated in OS X version 10.5 for 32-bit code, and disallowed for 64-bit code.”

Who Should Read This Document

The document is intended for readers who might be interested in learning about the Objective-C runtime.

Because this isn’t a document about C, it assumes some prior acquaintance with that language. However, it doesn’t have to be an extensive acquaintance.

Symbols

Working with Classes

func class_getName(AnyClass!)

Returns the name of a class.

func class_getSuperclass(AnyClass!)

Returns the superclass of a class.

func class_isMetaClass(AnyClass!)

Returns a Boolean value that indicates whether a class object is a metaclass.

func class_getInstanceSize(AnyClass!)

Returns the size of instances of a class.

func class_getInstanceVariable(AnyClass!, UnsafePointer<Int8>!)

Returns the Ivar for a specified instance variable of a given class.

func class_getClassVariable(AnyClass!, UnsafePointer<Int8>!)

Returns the Ivar for a specified class variable of a given class.

func class_copyIvarList(AnyClass!, UnsafeMutablePointer<UInt32>!)

Describes the instance variables declared by a class.

func class_getIvarLayout(AnyClass!)

Returns a description of the Ivar layout for a given class.

func class_setIvarLayout(AnyClass!, UnsafePointer<UInt8>!)

Sets the Ivar layout for a given class.

func class_getWeakIvarLayout(AnyClass!)

Returns a description of the layout of weak Ivars for a given class.

func class_setWeakIvarLayout(AnyClass!, UnsafePointer<UInt8>!)

Sets the layout for weak Ivars for a given class.

func class_getProperty(AnyClass!, UnsafePointer<Int8>!)

Returns a property with a given name of a given class.

func class_addMethod(AnyClass!, Selector!, IMP!, UnsafePointer<Int8>!)

Adds a new method to a class with a given name and implementation.

func class_getInstanceMethod(AnyClass!, Selector!)

Returns a specified instance method for a given class.

func class_getClassMethod(AnyClass!, Selector!)

Returns a pointer to the data structure describing a given class method for a given class.

func class_copyMethodList(AnyClass!, UnsafeMutablePointer<UInt32>!)

Describes the instance methods implemented by a class.

func class_replaceMethod(AnyClass!, Selector!, IMP!, UnsafePointer<Int8>!)

Replaces the implementation of a method for a given class.

func class_getMethodImplementation(AnyClass!, Selector!)

Returns the function pointer that would be called if a particular message were sent to an instance of a class.

func class_getMethodImplementation_stret(AnyClass!, Selector!)

Returns the function pointer that would be called if a particular message were sent to an instance of a class.

func class_respondsToSelector(AnyClass!, Selector!)

Returns a Boolean value that indicates whether instances of a class respond to a particular selector.

func class_conformsToProtocol(AnyClass!, Protocol!)

Returns a Boolean value that indicates whether a class conforms to a given protocol.

func class_getVersion(AnyClass!)

Returns the version number of a class definition.

func class_setVersion(AnyClass!, Int32)

Sets the version number of a class definition.

Adding Classes

func objc_disposeClassPair(AnyClass!)

Destroys a class and its associated metaclass.

func objc_registerClassPair(AnyClass!)

Registers a class that was allocated using objc_allocateClassPair(_:_:_:).

Working with Instances

func object_getIvar(Any!, Ivar!)

Reads the value of an instance variable in an object.

func object_setIvar(Any!, Ivar!, Any!)

Sets the value of an instance variable in an object.

func object_getClassName(Any!)
func object_getClass(Any!)

Returns the class of an object.

func object_setClass(Any!, AnyClass!)

Sets the class of an object.

Obtaining Class Definitions

func objc_copyClassList(UnsafeMutablePointer<UInt32>!)

Creates and returns a list of pointers to all registered class definitions.

func objc_lookUpClass(UnsafePointer<Int8>!)

Returns the class definition of a specified class.

func objc_getClass(UnsafePointer<Int8>!)

Returns the class definition of a specified class.

func objc_getRequiredClass(UnsafePointer<Int8>!)

Returns the class definition of a specified class.

func objc_getMetaClass(UnsafePointer<Int8>!)

Returns the metaclass definition of a specified class.

Working with Instance Variables

func ivar_getName(Ivar!)

Returns the name of an instance variable.

func ivar_getTypeEncoding(Ivar!)

Returns the type string of an instance variable.

func ivar_getOffset(Ivar!)

Returns the offset of an instance variable.

Associative References

func objc_setAssociatedObject(Any!, UnsafeRawPointer!, Any!, objc_AssociationPolicy)

Sets an associated value for a given object using a given key and association policy.

func objc_getAssociatedObject(Any!, UnsafeRawPointer!)

Returns the value associated with a given object for a given key.

func objc_removeAssociatedObjects(Any!)

Removes all associations for a given object.

Working with Methods

func method_getName(Method!)

Returns the name of a method.

func method_getImplementation(Method!)

Returns the implementation of a method.

func method_getTypeEncoding(Method!)

Returns a string describing a method's parameter and return types.

func method_copyReturnType(Method!)

Returns a string describing a method's return type.

func method_copyArgumentType(Method!, UInt32)

Returns a string describing a single parameter type of a method.

func method_getReturnType(Method!, UnsafeMutablePointer<Int8>!, Int)

Returns by reference a string describing a method's return type.

func method_getNumberOfArguments(Method!)

Returns the number of arguments accepted by a method.

func method_getArgumentType(Method!, UInt32, UnsafeMutablePointer<Int8>!, Int)

Returns by reference a string describing a single parameter type of a method.

func method_getDescription(Method!)

Returns a method description structure for a specified method.

func method_setImplementation(Method!, IMP!)

Sets the implementation of a method.

func method_exchangeImplementations(Method!, Method!)

Exchanges the implementations of two methods.

Working with Libraries

func objc_copyImageNames(UnsafeMutablePointer<UInt32>!)

Returns the names of all the loaded Objective-C frameworks and dynamic libraries.

func class_getImageName(AnyClass!)

Returns the name of the dynamic library a class originated from.

func objc_copyClassNamesForImage(UnsafePointer<Int8>!, UnsafeMutablePointer<UInt32>!)

Returns the names of all the classes within a specified library or framework.

Working with Protocols

func objc_getProtocol(UnsafePointer<Int8>!)

Returns a specified protocol.

func objc_copyProtocolList(UnsafeMutablePointer<UInt32>!)

Returns an array of all the protocols known to the runtime.

func objc_allocateProtocol(UnsafePointer<Int8>!)

Creates a new protocol instance.

func objc_registerProtocol(Protocol!)

Registers a newly created protocol with the Objective-C runtime.

func protocol_addProtocol(Protocol!, Protocol!)

Adds a registered protocol to another protocol that is under construction.

func protocol_getName(Protocol!)

Returns a the name of a protocol.

func protocol_isEqual(Protocol!, Protocol!)

Returns a Boolean value that indicates whether two protocols are equal.

func protocol_copyMethodDescriptionList(Protocol!, Bool, Bool, UnsafeMutablePointer<UInt32>!)

Returns an array of method descriptions of methods meeting a given specification for a given protocol.

func protocol_getMethodDescription(Protocol!, Selector!, Bool, Bool)

Returns a method description structure for a specified method of a given protocol.

func protocol_copyPropertyList(Protocol!, UnsafeMutablePointer<UInt32>!)

Returns an array of the properties declared by a protocol.

func protocol_getProperty(Protocol!, UnsafePointer<Int8>!, Bool, Bool)

Returns the specified property of a given protocol.

func protocol_copyProtocolList(Protocol!, UnsafeMutablePointer<UInt32>!)

Returns an array of the protocols adopted by a protocol.

func protocol_conformsToProtocol(Protocol!, Protocol!)

Returns a Boolean value that indicates whether one protocol conforms to another protocol.

Working with Properties

func property_getName(objc_property_t!)

Returns the name of a property.

func property_getAttributes(objc_property_t!)

Returns the attribute string of a property.

func property_copyAttributeValue(objc_property_t!, UnsafePointer<Int8>!)

Returns the value of a property attribute given the attribute name.

func property_copyAttributeList(objc_property_t!, UnsafeMutablePointer<UInt32>!)

Returns an array of property attributes for a given property.

Using Objective-C Language Features

func objc_enumerationMutation(Any!)

Inserted by the compiler when a mutation is detected during a foreach iteration.

func imp_implementationWithBlock(Any!)

Creates a pointer to a function that calls the specified block when the method is called.

func imp_getBlock(IMP!)

Returns the block associated with an IMP that was created using imp_implementationWithBlock(_:).

func imp_removeBlock(IMP!)

Disassociates a block from an IMP that was created using imp_implementationWithBlock(_:), and releases the copy of the block that was created.

func objc_loadWeak(AutoreleasingUnsafeMutablePointer<AnyObject?>!)

Loads the object referenced by a weak pointer and returns it.

Class-Definition Data Structures

Method

An opaque type that represents a method in a class definition.

Ivar

An opaque type that represents an instance variable.

Category

An opaque type that represents a category.

objc_property_t

An opaque type that represents an Objective-C declared property.

objc_method_description

Defines an Objective-C method.

objc_property_attribute_t

Instance Data Types

These are the data types that represent objects, classes, and superclasses.

objc_object
objc_super

Specifies the superclass of an instance.

Constants

Dispatch Function Prototypes

This macro indicates whether dispatch functions must be cast to an appropriate function pointer type.

Associative Object Behaviors

Policies related to associative references.