# Objective-C Runtime Describes the macOS Objective-C runtime library support functions and data structures. ## Discussion 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. > String encoding: > All `char *` in the runtime API should be considered to have UTF-8 encoding. “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. ## Topics ### Working with Classes [`class_getName(_:)`](/documentation/ObjectiveC/class_getName(_:)) Returns the name of a class. [`class_getSuperclass(_:)`](/documentation/ObjectiveC/class_getSuperclass(_:)) Returns the superclass of a class. [`class_setSuperclass(_:_:)`](/documentation/ObjectiveC/class_setSuperclass(_:_:)) Sets the superclass of a given class. [`class_isMetaClass(_:)`](/documentation/ObjectiveC/class_isMetaClass(_:)) Returns a Boolean value that indicates whether a class object is a metaclass. [`class_getInstanceSize(_:)`](/documentation/ObjectiveC/class_getInstanceSize(_:)) Returns the size of instances of a class. [`class_getInstanceVariable(_:_:)`](/documentation/ObjectiveC/class_getInstanceVariable(_:_:)) Returns the `Ivar` for a specified instance variable of a given class. [`class_getClassVariable(_:_:)`](/documentation/ObjectiveC/class_getClassVariable(_:_:)) Returns the `Ivar` for a specified class variable of a given class. [`class_addIvar(_:_:_:_:_:)`](/documentation/ObjectiveC/class_addIvar(_:_:_:_:_:)) Adds a new instance variable to a class. [`class_copyIvarList(_:_:)`](/documentation/ObjectiveC/class_copyIvarList(_:_:)) Describes the instance variables declared by a class. [`class_getIvarLayout(_:)`](/documentation/ObjectiveC/class_getIvarLayout(_:)) Returns a description of the `Ivar` layout for a given class. [`class_setIvarLayout(_:_:)`](/documentation/ObjectiveC/class_setIvarLayout(_:_:)) Sets the `Ivar` layout for a given class. [`class_getWeakIvarLayout(_:)`](/documentation/ObjectiveC/class_getWeakIvarLayout(_:)) Returns a description of the layout of weak `Ivar`s for a given class. [`class_setWeakIvarLayout(_:_:)`](/documentation/ObjectiveC/class_setWeakIvarLayout(_:_:)) Sets the layout for weak `Ivar`s for a given class. [`class_getProperty(_:_:)`](/documentation/ObjectiveC/class_getProperty(_:_:)) Returns a property with a given name of a given class. [`class_copyPropertyList(_:_:)`](/documentation/ObjectiveC/class_copyPropertyList(_:_:)) Describes the properties declared by a class. [`class_addMethod(_:_:_:_:)`](/documentation/ObjectiveC/class_addMethod(_:_:_:_:)) Adds a new method to a class with a given name and implementation. [`class_getInstanceMethod(_:_:)`](/documentation/ObjectiveC/class_getInstanceMethod(_:_:)) Returns a specified instance method for a given class. [`class_getClassMethod(_:_:)`](/documentation/ObjectiveC/class_getClassMethod(_:_:)) Returns a pointer to the data structure describing a given class method for a given class. [`class_copyMethodList(_:_:)`](/documentation/ObjectiveC/class_copyMethodList(_:_:)) Describes the instance methods implemented by a class. [`class_replaceMethod(_:_:_:_:)`](/documentation/ObjectiveC/class_replaceMethod(_:_:_:_:)) Replaces the implementation of a method for a given class. [`class_getMethodImplementation(_:_:)`](/documentation/ObjectiveC/class_getMethodImplementation(_:_:)) Returns the function pointer that would be called if a particular message were sent to an instance of a class. [`class_getMethodImplementation_stret(_:_:)`](/documentation/ObjectiveC/class_getMethodImplementation_stret(_:_:)) Returns the function pointer that would be called if a particular message were sent to an instance of a class. [`class_respondsToSelector(_:_:)`](/documentation/ObjectiveC/class_respondsToSelector(_:_:)) Returns a Boolean value that indicates whether instances of a class respond to a particular selector. [`class_addProtocol(_:_:)`](/documentation/ObjectiveC/class_addProtocol(_:_:)) Adds a protocol to a class. [`class_addProperty(_:_:_:_:)`](/documentation/ObjectiveC/class_addProperty(_:_:_:_:)) Adds a property to a class. [`class_replaceProperty(_:_:_:_:)`](/documentation/ObjectiveC/class_replaceProperty(_:_:_:_:)) Replace a property of a class. [`class_conformsToProtocol(_:_:)`](/documentation/ObjectiveC/class_conformsToProtocol(_:_:)) Returns a Boolean value that indicates whether a class conforms to a given protocol. [`class_copyProtocolList(_:_:)`](/documentation/ObjectiveC/class_copyProtocolList(_:_:)) Describes the protocols adopted by a class. [`class_getVersion(_:)`](/documentation/ObjectiveC/class_getVersion(_:)) Returns the version number of a class definition. [`class_setVersion(_:_:)`](/documentation/ObjectiveC/class_setVersion(_:_:)) Sets the version number of a class definition. [`objc_getFutureClass`](/documentation/ObjectiveC/objc_getFutureClass) Used by CoreFoundation’s toll-free bridging. [objc_setFutureClass](/documentation/ObjectiveC/1808430-objc_setfutureclass) Used by CoreFoundation’s toll-free bridging. ### Adding Classes [`objc_allocateClassPair(_:_:_:)`](/documentation/ObjectiveC/objc_allocateClassPair(_:_:_:)) Creates a new class and metaclass. [`objc_disposeClassPair(_:)`](/documentation/ObjectiveC/objc_disposeClassPair(_:)) Destroys a class and its associated metaclass. [`objc_registerClassPair(_:)`](/documentation/ObjectiveC/objc_registerClassPair(_:)) Registers a class that was allocated using [`objc_allocateClassPair(_:_:_:)`](/documentation/ObjectiveC/objc_allocateClassPair(_:_:_:)). [`objc_duplicateClass(_:_:_:)`](/documentation/ObjectiveC/objc_duplicateClass(_:_:_:)) Used by Foundation’s Key-Value Observing. ### Instantiating Classes [`class_createInstance(_:_:)`](/documentation/ObjectiveC/class_createInstance(_:_:)) Creates an instance of a class, allocating memory for the class in the default malloc memory zone. [`objc_constructInstance`](/documentation/ObjectiveC/objc_constructInstance) Creates an instance of a class at the specified location. [`objc_destructInstance`](/documentation/ObjectiveC/objc_destructInstance) Destroys an instance of a class without freeing memory and removes any of its associated references. ### Working with Instances [`object_copy`](/documentation/ObjectiveC/object_copy) Returns a copy of a given object. [`object_dispose`](/documentation/ObjectiveC/object_dispose) Frees the memory occupied by a given object. [`object_setInstanceVariable`](/documentation/ObjectiveC/object_setInstanceVariable) Changes the value of an instance variable of a class instance. [`object_getInstanceVariable`](/documentation/ObjectiveC/object_getInstanceVariable) Obtains the value of an instance variable of a class instance. [`object_getIndexedIvars(_:)`](/documentation/ObjectiveC/object_getIndexedIvars(_:)) Returns a pointer to any extra bytes allocated with a instance given object. [`object_getIvar(_:_:)`](/documentation/ObjectiveC/object_getIvar(_:_:)) Reads the value of an instance variable in an object. [`object_setIvar(_:_:_:)`](/documentation/ObjectiveC/object_setIvar(_:_:_:)) Sets the value of an instance variable in an object. [`object_getClassName(_:)`](/documentation/ObjectiveC/object_getClassName(_:)) Returns the class name of a given object. [`object_getClass(_:)`](/documentation/ObjectiveC/object_getClass(_:)) Returns the class of an object. [`object_setClass(_:_:)`](/documentation/ObjectiveC/object_setClass(_:_:)) Sets the class of an object. ### Obtaining Class Definitions [`objc_getClassList(_:_:)`](/documentation/ObjectiveC/objc_getClassList(_:_:)) Obtains the list of registered class definitions. [`objc_copyClassList(_:)`](/documentation/ObjectiveC/objc_copyClassList(_:)) Creates and returns a list of pointers to all registered class definitions. [`objc_lookUpClass(_:)`](/documentation/ObjectiveC/objc_lookUpClass(_:)) Returns the class definition of a specified class. [`objc_getClass(_:)`](/documentation/ObjectiveC/objc_getClass(_:)) Returns the class definition of a specified class. [`objc_getRequiredClass(_:)`](/documentation/ObjectiveC/objc_getRequiredClass(_:)) Returns the class definition of a specified class. [`objc_getMetaClass(_:)`](/documentation/ObjectiveC/objc_getMetaClass(_:)) Returns the metaclass definition of a specified class. ### Working with Instance Variables [`ivar_getName(_:)`](/documentation/ObjectiveC/ivar_getName(_:)) Returns the name of an instance variable. [`ivar_getTypeEncoding(_:)`](/documentation/ObjectiveC/ivar_getTypeEncoding(_:)) Returns the type string of an instance variable. [`ivar_getOffset(_:)`](/documentation/ObjectiveC/ivar_getOffset(_:)) Returns the offset of an instance variable. ### Associative References [`objc_setAssociatedObject(_:_:_:_:)`](/documentation/ObjectiveC/objc_setAssociatedObject(_:_:_:_:)) Sets an associated value for a given object using a given key and association policy. [`objc_getAssociatedObject(_:_:)`](/documentation/ObjectiveC/objc_getAssociatedObject(_:_:)) Returns the value associated with a given object for a given key. [`objc_removeAssociatedObjects(_:)`](/documentation/ObjectiveC/objc_removeAssociatedObjects(_:)) Removes all associations for a given object. ### Sending Messages When it encounters a method invocation, the compiler might generate a call to any of several functions to perform the actual message dispatch, depending on the receiver, the return value, and the arguments. You can use these functions to dynamically invoke methods from your own plain C code, or to use argument forms not permitted by NSObject’s `perform...` methods. These functions are declared in `/usr/include/objc/objc-runtime.h`. [`objc_msgSend`](/documentation/ObjectiveC/objc_msgSend) Sends a message with a simple return value to an instance of a class. [`objc_msgSend_fpret`](/documentation/ObjectiveC/objc_msgSend_fpret) Sends a message with a floating-point return value to an instance of a class. [`objc_msgSend_stret`](/documentation/ObjectiveC/objc_msgSend_stret) Sends a message with a data-structure return value to an instance of a class. [`objc_msgSendSuper`](/documentation/ObjectiveC/objc_msgSendSuper) Sends a message with a simple return value to the superclass of an instance of a class. [`objc_msgSendSuper_stret`](/documentation/ObjectiveC/objc_msgSendSuper_stret) Sends a message with a data-structure return value to the superclass of an instance of a class. ### Working with Methods [`method_invoke`](/documentation/ObjectiveC/method_invoke) Calls the implementation of a specified method. [`method_invoke_stret`](/documentation/ObjectiveC/method_invoke_stret) Calls the implementation of a specified method that returns a data-structure. [`method_getName(_:)`](/documentation/ObjectiveC/method_getName(_:)) Returns the name of a method. [`method_getImplementation(_:)`](/documentation/ObjectiveC/method_getImplementation(_:)) Returns the implementation of a method. [`method_getTypeEncoding(_:)`](/documentation/ObjectiveC/method_getTypeEncoding(_:)) Returns a string describing a method’s parameter and return types. [`method_copyReturnType(_:)`](/documentation/ObjectiveC/method_copyReturnType(_:)) Returns a string describing a method’s return type. [`method_copyArgumentType(_:_:)`](/documentation/ObjectiveC/method_copyArgumentType(_:_:)) Returns a string describing a single parameter type of a method. [`method_getReturnType(_:_:_:)`](/documentation/ObjectiveC/method_getReturnType(_:_:_:)) Returns by reference a string describing a method’s return type. [`method_getNumberOfArguments(_:)`](/documentation/ObjectiveC/method_getNumberOfArguments(_:)) Returns the number of arguments accepted by a method. [`method_getArgumentType(_:_:_:_:)`](/documentation/ObjectiveC/method_getArgumentType(_:_:_:_:)) Returns by reference a string describing a single parameter type of a method. [`method_getDescription(_:)`](/documentation/ObjectiveC/method_getDescription(_:)) Returns a method description structure for a specified method. [`method_setImplementation(_:_:)`](/documentation/ObjectiveC/method_setImplementation(_:_:)) Sets the implementation of a method. [`method_exchangeImplementations(_:_:)`](/documentation/ObjectiveC/method_exchangeImplementations(_:_:)) Exchanges the implementations of two methods. ### Working with Libraries [`objc_copyImageNames(_:)`](/documentation/ObjectiveC/objc_copyImageNames(_:)) Returns the names of all the loaded Objective-C frameworks and dynamic libraries. [`class_getImageName(_:)`](/documentation/ObjectiveC/class_getImageName(_:)) Returns the name of the dynamic library a class originated from. [`objc_copyClassNamesForImage(_:_:)`](/documentation/ObjectiveC/objc_copyClassNamesForImage(_:_:)) Returns the names of all the classes within a specified library or framework. ### Working with Selectors [`sel_getName(_:)`](/documentation/ObjectiveC/sel_getName(_:)) Returns the name of the method specified by a given selector. [`sel_registerName(_:)`](/documentation/ObjectiveC/sel_registerName(_:)) Registers a method with the Objective-C runtime system, maps the method name to a selector, and returns the selector value. [`sel_getUid(_:)`](/documentation/ObjectiveC/sel_getUid(_:)) Registers a method name with the Objective-C runtime system. [`sel_isEqual(_:_:)`](/documentation/ObjectiveC/sel_isEqual(_:_:)) Returns a Boolean value that indicates whether two selectors are equal. ### Working with Protocols [`objc_getProtocol(_:)`](/documentation/ObjectiveC/objc_getProtocol(_:)) Returns a specified protocol. [`objc_copyProtocolList(_:)`](/documentation/ObjectiveC/objc_copyProtocolList(_:)) Returns an array of all the protocols known to the runtime. [`objc_allocateProtocol(_:)`](/documentation/ObjectiveC/objc_allocateProtocol(_:)) Creates a new protocol instance. [`objc_registerProtocol(_:)`](/documentation/ObjectiveC/objc_registerProtocol(_:)) Registers a newly created protocol with the Objective-C runtime. [`protocol_addMethodDescription(_:_:_:_:_:)`](/documentation/ObjectiveC/protocol_addMethodDescription(_:_:_:_:_:)) Adds a method to a protocol. [`protocol_addProtocol(_:_:)`](/documentation/ObjectiveC/protocol_addProtocol(_:_:)) Adds a registered protocol to another protocol that is under construction. [`protocol_addProperty(_:_:_:_:_:_:)`](/documentation/ObjectiveC/protocol_addProperty(_:_:_:_:_:_:)) Adds a property to a protocol that is under construction. [`protocol_getName(_:)`](/documentation/ObjectiveC/protocol_getName(_:)) Returns the name of a protocol. [`protocol_isEqual(_:_:)`](/documentation/ObjectiveC/protocol_isEqual(_:_:)) Returns a Boolean value that indicates whether two protocols are equal. [`protocol_copyMethodDescriptionList(_:_:_:_:)`](/documentation/ObjectiveC/protocol_copyMethodDescriptionList(_:_:_:_:)) Returns an array of method descriptions of methods meeting a given specification for a given protocol. [`protocol_getMethodDescription(_:_:_:_:)`](/documentation/ObjectiveC/protocol_getMethodDescription(_:_:_:_:)) Returns a method description structure for a specified method of a given protocol. [`protocol_copyPropertyList(_:_:)`](/documentation/ObjectiveC/protocol_copyPropertyList(_:_:)) Returns an array of the properties declared by a protocol. [`protocol_getProperty(_:_:_:_:)`](/documentation/ObjectiveC/protocol_getProperty(_:_:_:_:)) Returns the specified property of a given protocol. [`protocol_copyProtocolList(_:_:)`](/documentation/ObjectiveC/protocol_copyProtocolList(_:_:)) Returns an array of the protocols adopted by a protocol. [`protocol_conformsToProtocol(_:_:)`](/documentation/ObjectiveC/protocol_conformsToProtocol(_:_:)) Returns a Boolean value that indicates whether one protocol conforms to another protocol. ### Working with Properties [`property_getName(_:)`](/documentation/ObjectiveC/property_getName(_:)) Returns the name of a property. [`property_getAttributes(_:)`](/documentation/ObjectiveC/property_getAttributes(_:)) Returns the attribute string of a property. [`property_copyAttributeValue(_:_:)`](/documentation/ObjectiveC/property_copyAttributeValue(_:_:)) Returns the value of a property attribute given the attribute name. [`property_copyAttributeList(_:_:)`](/documentation/ObjectiveC/property_copyAttributeList(_:_:)) Returns an array of property attributes for a given property. ### Using Objective-C Language Features [`objc_enumerationMutation(_:)`](/documentation/ObjectiveC/objc_enumerationMutation(_:)) Inserted by the compiler when a mutation is detected during a foreach iteration. [`objc_setEnumerationMutationHandler(_:)`](/documentation/ObjectiveC/objc_setEnumerationMutationHandler(_:)) Sets the current mutation handler. [`imp_implementationWithBlock(_:)`](/documentation/ObjectiveC/imp_implementationWithBlock(_:)) Creates a pointer to a function that calls the specified block when the method is called. [`imp_getBlock(_:)`](/documentation/ObjectiveC/imp_getBlock(_:)) Returns the block associated with an `IMP` that was created using [`imp_implementationWithBlock(_:)`](/documentation/ObjectiveC/imp_implementationWithBlock(_:)). [`imp_removeBlock(_:)`](/documentation/ObjectiveC/imp_removeBlock(_:)) Disassociates a block from an `IMP` that was created using [`imp_implementationWithBlock(_:)`](/documentation/ObjectiveC/imp_implementationWithBlock(_:)), and releases the copy of the block that was created. [`objc_loadWeak(_:)`](/documentation/ObjectiveC/objc_loadWeak(_:)) Loads the object referenced by a weak pointer and returns it. [`objc_storeWeak(_:_:)`](/documentation/ObjectiveC/objc_storeWeak(_:_:)) Stores a new value in a `__weak` variable. ### Class-Definition Data Structures [`Class`](/documentation/ObjectiveC/Class) An opaque type that represents an Objective-C class. [`Method`](/documentation/ObjectiveC/Method) An opaque type that represents a method in a class definition. [`Ivar`](/documentation/ObjectiveC/Ivar) An opaque type that represents an instance variable. [`Category`](/documentation/ObjectiveC/Category) An opaque type that represents a category. [`objc_property_t`](/documentation/ObjectiveC/objc_property_t) An opaque type that represents an Objective-C declared property. [`IMP`](/documentation/ObjectiveC/IMP) A pointer to the start of a method implementation. [`SEL`](/documentation/ObjectiveC/SEL) Defines an opaque type that represents a method selector. [`objc_method_description`](/documentation/ObjectiveC/objc_method_description) Defines an Objective-C method. [objc_cache](/documentation/ObjectiveC/objc_cache) Performance optimization for method calls. Contains pointers to recently used methods. [`objc_property_attribute_t`](/documentation/ObjectiveC/objc_property_attribute_t) Defines a property attribute. ### Instance Data Types These are the data types that represent objects, classes, and superclasses. [`objc_object`](/documentation/ObjectiveC/objc_object) Represents an instance of a class. [`id`](/documentation/ObjectiveC/id) A pointer to an instance of a class. [`objc_super`](/documentation/ObjectiveC/objc_super-swift.struct) Specifies the superclass of an instance. ### Boolean Value [`BOOL`](/documentation/ObjectiveC/BOOL) Type to represent a Boolean value. ### Associative References [`objc_AssociationPolicy`](/documentation/ObjectiveC/objc_AssociationPolicy) Type to specify the behavior of an association. ### Constants [Boolean Values](/documentation/ObjectiveC/boolean-values) These macros define convenient constants to represent Boolean values. [Null Values](/documentation/ObjectiveC/null-values) These macros define null values for classes and instances. [Dispatch Function Prototypes](/documentation/ObjectiveC/dispatch-function-prototypes) This macro indicates whether dispatch functions must be cast to an appropriate function pointer type. [Objective-C Root Class](/documentation/ObjectiveC/objective-c-root-class) This macro annotates a class as being an Objective-C root class. [Local Variable Storage Duration](/documentation/ObjectiveC/local-variable-storage-duration) This macro indicates that the values stored in certain local variables should not be aggressively released by the compiler during optimization. ## See Also [Objective-C Runtime Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40008048) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)