GNU Objective-C Runtime API

This section is specific for the GNU Objective-C runtime. If you are using a different runtime, you can skip it.

The GNU Objective-C runtime provides an API that allows you to interact with the Objective-C runtime system, querying the live runtime structures and even manipulating them. This allows you for example to inspect and navigate classes, methods and protocols; to define new classes or new methods, and even to modify existing classes or protocols.

If you are using a ‘Foundation’ library such as GNUstep-Base, this library will provide you with a rich set of functionality to do most of the inspection tasks, and you probably will only need direct access to the GNU Objective-C runtime API to define new classes or methods.

Modern GNU Objective-C Runtime API

The GNU Objective-C runtime provides an API which is similar to the one provided by the ‘Objective-C 2.0’ Apple/NeXT Objective-C runtime. The API is documented in the public header files of the GNU Objective-C runtime:

• objc/objc.h: this is the basic Objective-C header file, defining the basic Objective-C types such as id, Class and BOOL. You have to include this header to do almost anything with Objective-C.
• objc/runtime.h: this header declares most of the public runtime API functions allowing you to inspect and manipulate the Objective-C runtime data structures. These functions are fairly standardized across Objective-C runtimes and are almost identical to the Apple/NeXT Objective-C runtime ones. It does not declare functions in some specialized areas (constructing and forwarding message invocations, threading) which are in the other headers below. You have to include objc/objc.h and objc/runtime.h to use any of the functions, such as class_getName(), declared in objc/runtime.h.
• objc/message.h: this header declares public functions used to construct, deconstruct and forward message invocations. Because messaging is done in quite a different way on different runtimes, functions in this header are specific to the GNU Objective-C runtime implementation.
• objc/objc-exception.h: this header declares some public functions related to Objective-C exceptions. For example functions in this header allow you to throw an Objective-C exception from plain C/C++ code.
• objc/objc-sync.h: this header declares some public functions related to the Objective-C @synchronized() syntax, allowing you to emulate an Objective-C @synchronized() block in plain C/C++ code.
• objc/thr.h: this header declares a public runtime API threading layer that is only provided by the GNU Objective-C runtime. It declares functions such as objc_mutex_lock(), which provide a platform-independent set of threading functions.

The header files contain detailed documentation for each function in the GNU Objective-C runtime API.

Traditional GNU Objective-C Runtime API

The GNU Objective-C runtime used to provide a different API, which we call the ‘traditional’ GNU Objective-C runtime API. Functions belonging to this API are easy to recognize because they use a different naming convention, such as class_get_super_class() (traditional API) instead of class_getSuperclass() (modern API). Software using this API includes the file objc/objc-api.h where it is declared.

Starting with GCC 4.7.0, the traditional GNU runtime API is no longer available.