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(an​Instance) to 32 bits, and three other values to 24 bits—methods per class, ivars per class, and sizeof(a single ivar). Finally, the obsolete NXHash​Table and NXMap​Table 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_get​Name(Any​Class!)

Returns the name of a class.

func class_get​Superclass(Any​Class!)

Returns the superclass of a class.

func class_is​Meta​Class(Any​Class!)

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

func class_get​Instance​Size(Any​Class!)

Returns the size of instances of a class.

func class_get​Instance​Variable(Any​Class!, Unsafe​Pointer<Int8>!)

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

func class_get​Class​Variable(Any​Class!, Unsafe​Pointer<Int8>!)

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

func class_get​Ivar​Layout(Any​Class!)

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

func class_get​Weak​Ivar​Layout(Any​Class!)

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

func class_get​Property(Any​Class!, Unsafe​Pointer<Int8>!)

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

func class_add​Method(Any​Class!, Selector!, IMP!, Unsafe​Pointer<Int8>!)

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

func class_get​Instance​Method(Any​Class!, Selector!)

Returns a specified instance method for a given class.

func class_get​Class​Method(Any​Class!, Selector!)

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

func class_replace​Method(Any​Class!, Selector!, IMP!, Unsafe​Pointer<Int8>!)

Replaces the implementation of a method for a given class.

func class_get​Method​Implementation(Any​Class!, Selector!)

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

func class_get​Method​Implementation_stret(Any​Class!, Selector!)

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

func class_responds​To​Selector(Any​Class!, Selector!)

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

func class_conforms​To​Protocol(Any​Class!, Protocol!)

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

func class_get​Version(Any​Class!)

Returns the version number of a class definition.

func class_set​Version(Any​Class!, Int32)

Sets the version number of a class definition.

Adding Classes

func objc_dispose​Class​Pair(Any​Class!)

Destroys a class and its associated metaclass.

func objc_register​Class​Pair(Any​Class!)

Registers a class that was allocated using objc_allocate​Class​Pair(_:​_:​_:​).

Working with Instances

func object_get​Ivar(Any!, Ivar!)

Reads the value of an instance variable in an object.

func object_set​Ivar(Any!, Ivar!, Any!)

Sets the value of an instance variable in an object.

func object_get​Class​Name(Any!)
func object_get​Class(Any!)

Returns the class of an object.

Obtaining Class Definitions

func objc_copy​Class​List(Unsafe​Mutable​Pointer<UInt32>!)

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

func objc_look​Up​Class(Unsafe​Pointer<Int8>!)

Returns the class definition of a specified class.

func objc_get​Class(Unsafe​Pointer<Int8>!)

Returns the class definition of a specified class.

func objc_get​Required​Class(Unsafe​Pointer<Int8>!)

Returns the class definition of a specified class.

func objc_get​Meta​Class(Unsafe​Pointer<Int8>!)

Returns the metaclass definition of a specified class.

Working with Instance Variables

func ivar_get​Name(Ivar!)

Returns the name of an instance variable.

func ivar_get​Type​Encoding(Ivar!)

Returns the type string of an instance variable.

func ivar_get​Offset(Ivar!)

Returns the offset of an instance variable.

Associative References

func objc_set​Associated​Object(Any!, Unsafe​Raw​Pointer!, Any!, objc_Association​Policy)

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

func objc_get​Associated​Object(Any!, Unsafe​Raw​Pointer!)

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

func objc_remove​Associated​Objects(Any!)

Removes all associations for a given object.

Working with Methods

func method_get​Name(Method!)

Returns the name of a method.

func method_get​Implementation(Method!)

Returns the implementation of a method.

func method_get​Type​Encoding(Method!)

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

func method_copy​Return​Type(Method!)

Returns a string describing a method's return type.

func method_copy​Argument​Type(Method!, UInt32)

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

func method_get​Return​Type(Method!, Unsafe​Mutable​Pointer<Int8>!, Int)

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

func method_get​Number​Of​Arguments(Method!)

Returns the number of arguments accepted by a method.

func method_get​Argument​Type(Method!, UInt32, Unsafe​Mutable​Pointer<Int8>!, Int)

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

func method_get​Description(Method!)

Returns a method description structure for a specified method.

func method_set​Implementation(Method!, IMP!)

Sets the implementation of a method.

func method_exchange​Implementations(Method!, Method!)

Exchanges the implementations of two methods.

Working with Libraries

func objc_copy​Image​Names(Unsafe​Mutable​Pointer<UInt32>!)

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

func class_get​Image​Name(Any​Class!)

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

func objc_copy​Class​Names​For​Image(Unsafe​Pointer<Int8>!, Unsafe​Mutable​Pointer<UInt32>!)

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

Working with Protocols

func objc_copy​Protocol​List(Unsafe​Mutable​Pointer<UInt32>!)

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

func objc_register​Protocol(Protocol!)

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

func protocol_add​Protocol(Protocol!, Protocol!)

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

func protocol_get​Name(Protocol!)

Returns a the name of a protocol.

func protocol_is​Equal(Protocol!, Protocol!)

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

func protocol_copy​Method​Description​List(Protocol!, Bool, Bool, Unsafe​Mutable​Pointer<UInt32>!)

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

func protocol_get​Method​Description(Protocol!, Selector!, Bool, Bool)

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

func protocol_copy​Property​List(Protocol!, Unsafe​Mutable​Pointer<UInt32>!)

Returns an array of the properties declared by a protocol.

func protocol_get​Property(Protocol!, Unsafe​Pointer<Int8>!, Bool, Bool)

Returns the specified property of a given protocol.

func protocol_copy​Protocol​List(Protocol!, Unsafe​Mutable​Pointer<UInt32>!)

Returns an array of the protocols adopted by a protocol.

func protocol_conforms​To​Protocol(Protocol!, Protocol!)

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

Working with Properties

func property_get​Name(objc_property_t!)

Returns the name of a property.

func property_get​Attributes(objc_property_t!)

Returns the attribute string of a property.

func property_copy​Attribute​Value(objc_property_t!, Unsafe​Pointer<Int8>!)

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

func property_copy​Attribute​List(objc_property_t!, Unsafe​Mutable​Pointer<UInt32>!)

Returns an array of property attributes for a given property.

Using Objective-C Language Features

func objc_enumeration​Mutation(Any!)

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

func imp_implementation​With​Block(Any!)

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

func imp_get​Block(IMP!)

Returns the block associated with an IMP that was created using imp_implementation​With​Block(_:​).

func imp_remove​Block(IMP!)

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

func objc_load​Weak(Autoreleasing​Unsafe​Mutable​Pointer<Any​Object?>!)

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.

See Also