Objective-C Runtime Reference

This document describes the OS X Objective-C 2.0 runtime library support functions and data structures. The functions are implemented in the shared library found at /usr/lib/libobjc.A.dylib. This shared library provides support for the dynamic properties of the Objective-C language, and as such is linked to by all Objective-C applications.

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

The OS X 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 OS X 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.

Functions

Working with Classes

Adding Classes

Instantiating Classes

Working with Instances

Obtaining Class Definitions

Working with Instance Variables

Associative References

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.

Working with Methods

Working with Libraries

Working with Selectors

Working with Protocols

Working with Properties

Using Objective-C Language Features

Data Types

Class-Definition Data Structures

Instance Data Types

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

id pointer to an instance of a class.
objc_object represents an instance of a class.
objc_super specifies the superclass of an instance.

Boolean Value

BOOL

Associative References

objc_AssociationPolicy

Constants