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
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/runtime.hto use any of the functions, such as
class_getName(), declared in
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
(traditional API) instead of
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.