Objective-C Runtime

Describes the macOS Objective-C 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.

Topics

Working with Classes

class_getName

Returns the name of a class.

class_getSuperclass

Returns the superclass of a class.

class_setSuperclass

Sets the superclass of a given class.

Deprecated
class_isMetaClass

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

class_getInstanceSize

Returns the size of instances of a class.

class_getInstanceVariable

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

class_getClassVariable

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

class_addIvar

Adds a new instance variable to a class.

class_copyIvarList

Describes the instance variables declared by a class.

class_getIvarLayout

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

class_setIvarLayout

Sets the Ivar layout for a given class.

class_getWeakIvarLayout

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

class_setWeakIvarLayout

Sets the layout for weak Ivars for a given class.

class_getProperty

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

class_copyPropertyList

Describes the properties declared by a class.

class_addMethod

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

class_getInstanceMethod

Returns a specified instance method for a given class.

class_getClassMethod

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

class_copyMethodList

Describes the instance methods implemented by a class.

class_replaceMethod

Replaces the implementation of a method for a given class.

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

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

class_respondsToSelector

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

class_addProtocol

Adds a protocol to a class.

class_addProperty

Adds a property to a class.

class_replaceProperty

Replace a property of a class.

class_conformsToProtocol

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

class_copyProtocolList

Describes the protocols adopted by a class.

class_getVersion

Returns the version number of a class definition.

class_setVersion

Sets the version number of a class definition.

objc_getFutureClass

Used by CoreFoundation's toll-free bridging.

objc_setFutureClass

Used by CoreFoundation's toll-free bridging.

Adding Classes

objc_allocateClassPair

Creates a new class and metaclass.

objc_disposeClassPair

Destroys a class and its associated metaclass.

objc_registerClassPair

Registers a class that was allocated using objc_allocateClassPair.

objc_duplicateClass

Used by Foundation's Key-Value Observing.

Instantiating Classes

class_createInstance

Creates an instance of a class, allocating memory for the class in the default malloc memory zone.

objc_constructInstance

Creates an instance of a class at the specified location.

objc_destructInstance

Destroys an instance of a class without freeing memory and removes any of its associated references.

Working with Instances

object_copy

Returns a copy of a given object.

object_dispose

Frees the memory occupied by a given object.

object_setInstanceVariable

Changes the value of an instance variable of a class instance.

object_getInstanceVariable

Obtains the value of an instance variable of a class instance.

object_getIndexedIvars

Returns a pointer to any extra bytes allocated with a instance given object.

object_getIvar

Reads the value of an instance variable in an object.

object_setIvar

Sets the value of an instance variable in an object.

object_getClassName

Returns the class name of a given object.

object_getClass

Returns the class of an object.

object_setClass

Sets the class of an object.

Obtaining Class Definitions

objc_getClassList

Obtains the list of registered class definitions.

objc_copyClassList

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

objc_lookUpClass

Returns the class definition of a specified class.

objc_getClass

Returns the class definition of a specified class.

objc_getRequiredClass

Returns the class definition of a specified class.

objc_getMetaClass

Returns the metaclass definition of a specified class.

Working with Instance Variables

ivar_getName

Returns the name of an instance variable.

ivar_getTypeEncoding

Returns the type string of an instance variable.

ivar_getOffset

Returns the offset of an instance variable.

Associative References

objc_setAssociatedObject

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

objc_getAssociatedObject

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

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 sends a message with a simple return value to an instance of a class.

  • objc_msgSend_stret sends a message with a data-structure return value to an instance of a class.

  • objc_msgSendSuper sends a message with a simple return value to the superclass of an instance of a class.

  • objc_msgSendSuper_stret sends a message with a data-structure return value to the superclass of an instance of a class.

objc_msgSend

Sends a message with a simple return value to an instance of a class.

objc_msgSend_fpret

Sends a message with a floating-point return value to an instance of a class.

objc_msgSend_stret

Sends a message with a data-structure return value to an instance of a class.

objc_msgSendSuper

Sends a message with a simple return value to the superclass of an instance of a class.

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

Calls the implementation of a specified method.

method_invoke_stret

Calls the implementation of a specified method that returns a data-structure.

method_getName

Returns the name of a method.

method_getImplementation

Returns the implementation of a method.

method_getTypeEncoding

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

method_copyReturnType

Returns a string describing a method's return type.

method_copyArgumentType

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

method_getReturnType

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

method_getNumberOfArguments

Returns the number of arguments accepted by a method.

method_getArgumentType

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

method_getDescription

Returns a method description structure for a specified method.

method_setImplementation

Sets the implementation of a method.

method_exchangeImplementations

Exchanges the implementations of two methods.

Working with Libraries

objc_copyImageNames

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

class_getImageName

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

objc_copyClassNamesForImage

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

Working with Selectors

sel_getName

Returns the name of the method specified by a given selector.

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

Registers a method name with the Objective-C runtime system.

sel_isEqual

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

Working with Protocols

objc_getProtocol

Returns a specified protocol.

objc_copyProtocolList

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

objc_allocateProtocol

Creates a new protocol instance.

objc_registerProtocol

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

protocol_addMethodDescription

Adds a method to a protocol.

protocol_addProtocol

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

protocol_addProperty

Adds a property to a protocol that is under construction.

protocol_getName

Returns a the name of a protocol.

protocol_isEqual

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

protocol_copyMethodDescriptionList

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

protocol_getMethodDescription

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

protocol_copyPropertyList

Returns an array of the properties declared by a protocol.

protocol_getProperty

Returns the specified property of a given protocol.

protocol_copyProtocolList

Returns an array of the protocols adopted by a protocol.

protocol_conformsToProtocol

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

Working with Properties

property_getName

Returns the name of a property.

property_getAttributes

Returns the attribute string of a property.

property_copyAttributeValue

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

property_copyAttributeList

Returns an array of property attributes for a given property.

Using Objective-C Language Features

objc_enumerationMutation

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

objc_setEnumerationMutationHandler

Sets the current mutation handler.

imp_implementationWithBlock

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

imp_getBlock

Returns the block associated with an IMP that was created using imp_implementationWithBlock.

imp_removeBlock

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

objc_loadWeak

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

objc_storeWeak

Stores a new value in a __weak variable.

Class-Definition Data Structures

Class

An opaque type that represents an Objective-C class.

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.

IMP

A pointer to the start of a method implementation.

SEL

Defines an opaque type that represents a method selector.

objc_method_description

Defines an Objective-C method.

objc_method_list

Contains an array of method definitions.

Deprecated
objc_cache

Performance optimization for method calls. Contains pointers to recently used methods.

objc_protocol_list

Represents a list of formal protocols.

objc_property_attribute_t

Defines a property attribute.

Instance Data Types

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

  • id pointer to an instance of a class.

  • id represents an instance of a class.

  • objc_super specifies the superclass of an instance.

id

A pointer to an instance of a class.

objc_super

Specifies the superclass of an instance.

Boolean Value

BOOL

Type to represent a Boolean value.

Associative References

objc_AssociationPolicy

Type to specify the behavior of an association.

Constants

Boolean Values

These macros define convenient constants to represent Boolean values.

Null Values

These macros define null values for classes and instances.

Dispatch Function Prototypes

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

Objective-C Root Class

This macro annotates a class as being an Objective-C root class.

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