1 /* GNU Objective-C Runtime API - Modern API
2 Copyright (C) 2010 Free Software Foundation, Inc.
3 Contributed by Nicola Pero <nicola.pero@meta-innovation.com>
5 This file is part of GCC.
7 GCC is free software; you can redistribute it and/or modify it
8 under the terms of the GNU General Public License as published by the
9 Free Software Foundation; either version 3, or (at your option) any
12 GCC is distributed in the hope that it will be useful, but WITHOUT
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
15 License for more details.
17 Under Section 7 of GPL version 3, you are granted additional
18 permissions described in the GCC Runtime Library Exception, version
19 3.1, as published by the Free Software Foundation.
21 You should have received a copy of the GNU General Public License and
22 a copy of the GCC Runtime Library Exception along with this program;
23 see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
24 <http://www.gnu.org/licenses/>. */
26 #ifndef __objc_runtime_INCLUDE_GNU
27 #define __objc_runtime_INCLUDE_GNU
30 This file declares the "modern" GNU Objective-C Runtime API.
31 Include this file to use it.
33 This API is replacing the "traditional" GNU Objective-C Runtime API
34 (declared in objc/objc-api.h) which is the one supported by older
35 versions of the GNU Objective-C Runtime. The "modern" API is very
36 similar to the API used by the modern Apple/NeXT runtime.
38 Because the two APIs have some conflicting definitions (in
39 particular, Method and Category are defined differently) you should
40 include either objc/objc-api.h (to use the traditional GNU
41 Objective-C Runtime API) or objc/runtime.h (to use the modern GNU
42 Objective-C Runtime API), but not both.
44 #ifdef __objc_api_INCLUDE_GNU
45 # error You can not include both objc/objc-api.h and objc/runtime.h. Include objc/objc-api.h for the traditional GNU Objective-C Runtime API and objc/runtime.h for the modern one.
48 /* TODO: This file is incomplete. */
51 #include "objc-decls.h"
53 /* An 'Ivar' represents an instance variable. It holds information
54 about the name, type and offset of the instance variable. */
55 typedef struct objc_ivar
*Ivar
;
57 /* A 'Property' represents a property. It holds information about the
58 name of the property, and its attributes.
60 Compatibility Note: the Apple/NeXT runtime defines this as
61 objc_property_t, so we define it that way as well, but obviously
62 Property is the right name. */
63 typedef struct objc_property
*Property
;
64 typedef struct objc_property
*objc_property_t
;
66 /* A 'Method' represents a method. It holds information about the
67 name, types and the IMP of the method. */
68 typedef struct objc_method
*Method
;
70 /* A 'Category' represents a category. It holds information about the
71 name of the category, the class it belongs to, and the methods,
72 protocols and such like provided by the category. */
73 typedef struct objc_category
*Category
;
75 /* 'Protocol' is defined in objc/objc.h (which is included by this
78 /* Method descriptor returned by introspective Object methods. At the
79 moment, this is really just the first part of the more complete
80 objc_method structure used internally by the runtime. (PS: In the
81 GNU Objective-C Runtime, selectors already include a type, so an
82 objc_method_description does not add much to a SEL. But in other
83 runtimes, that is not the case, which is why
84 objc_method_description exists). */
85 struct objc_method_description
87 SEL name
; /* Selector (name and signature) */
88 char *types
; /* Type encoding */
91 /* The following are used in encode strings to describe the type of
104 #define _C_LNG_LNG 'q'
105 #define _C_ULNG_LNG 'Q'
108 #define _C_LNG_DBL 'D'
114 #define _C_CHARPTR '*'
117 #define _C_UNION_B '('
118 #define _C_UNION_E ')'
119 #define _C_STRUCT_B '{'
120 #define _C_STRUCT_E '}'
121 #define _C_VECTOR '!'
122 #define _C_COMPLEX 'j'
124 /* _C_ATOM is never generated by the compiler. You can treat it as
125 equivalent to "*". */
128 /* The following are used in encode strings to describe some
129 qualifiers of method and ivar types. */
134 #define _C_BYCOPY 'O'
136 #define _C_ONEWAY 'V'
137 #define _C_GCINVISIBLE '|'
139 /* The same when used as flags. */
140 #define _F_CONST 0x01
143 #define _F_INOUT 0x03
144 #define _F_BYCOPY 0x04
145 #define _F_BYREF 0x08
146 #define _F_ONEWAY 0x10
147 #define _F_GCINVISIBLE 0x20
150 /** Implementation: the following functions are defined inline. */
152 /* Return the class of 'object', or Nil if the object is nil. If
153 'object' is a class, the meta class is returned; if 'object' is a
154 meta class, the root meta class is returned (note that this is
155 different from the traditional GNU Objective-C Runtime API function
156 object_get_class(), which for a meta class would return the meta
157 class itself). This function is inline, so it is really fast and
158 should be used instead of accessing object->class_pointer
161 object_getClass (id object
)
164 return object
->class_pointer
;
170 /** Implementation: the following functions are in selector.c. */
172 /* Return the name of a given selector. If 'selector' is NULL, return
173 "<null selector>". */
174 objc_EXPORT
const char *sel_getName (SEL selector
);
176 /* Return the type of a given selector.
178 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
179 so it does not have this function, which is specific to the GNU
181 objc_EXPORT
const char *sel_getType (SEL selector
);
183 /* This is the same as sel_registerName (). Please use
184 sel_registerName () instead. */
185 objc_EXPORT SEL
sel_getUid (const char *name
);
187 /* Register a selector with a given name (but unspecified types). If
188 you know the types, it is better to call sel_registerTypedName().
189 If a selector with this name already exists, it is returned. */
190 objc_EXPORT SEL
sel_registerName (const char *name
);
192 /* Register a selector with a given name and types. If a selector
193 with this name and types already exists, it is returned.
195 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
196 so it does not have this function, which is specific to the GNU
198 objc_EXPORT SEL
sel_registerTypedName (const char *name
, const char *type
);
200 /* Return YES if first_selector is the same as second_selector, and NO
202 objc_EXPORT BOOL
sel_isEqual (SEL first_selector
, SEL second_selector
);
205 /** Implementation: the following functions are in objects.c. */
207 /* Create an instance of class 'class_', adding extraBytes to the size
208 of the returned object. This method allocates the appropriate
209 amount of memory for the instance, initializes it to zero, then
210 calls all the C++ constructors on appropriate C++ instance
211 variables of the instance (if any) (TODO: The C++ constructors bit
212 is not implemented yet). */
213 objc_EXPORT id
class_createInstance (Class class_
, size_t extraBytes
);
215 /* Copy an object and return the copy. extraBytes should be identical
216 to the extraBytes parameter that was passed when creating the
218 objc_EXPORT id
object_copy (id object
, size_t extraBytes
);
220 /* Dispose of an object. This method calls the appropriate C++
221 destructors on appropriate C++ instance variables of the instance
222 (if any) (TODO: This is not implemented yet), then frees the memory
224 objc_EXPORT id
object_dispose (id object
);
226 /* Return the name of the class of 'object'. If 'object' is 'nil',
228 objc_EXPORT
const char * object_getClassName (id object
);
230 /* Change the class of object to be class_. Return the previous class
231 of object. This is currently not really thread-safe. */
232 objc_EXPORT Class
object_setClass (id object
, Class class_
);
235 /** Implementation: the following functions are in ivars.c. */
237 /* Return an instance variable given the class and the instance
238 variable name. This is an expensive function to call, so try to
239 reuse the returned Ivar if you can. */
240 objc_EXPORT Ivar
class_getInstanceVariable (Class class_
, const char *name
);
242 /* Return a class variable given the class and the class variable
243 name. This is an expensive function to call, so try to reuse the
244 returned Ivar if you can.
246 This function always returns NULL since class variables are
247 currently unavailable in Objective-C. */
248 objc_EXPORT Ivar
class_getClassVariable (Class class_
, const char *name
);
250 /* If the object was created in class_createInstance() with some
251 extraBytes, returns a pointer to them. If it was not, then the
252 returned pointer may make no sense. */
253 objc_EXPORT
void * object_getIndexedIvars (id object
);
255 /* Get the value of an instance variable of type 'id'. The function
256 returns the instance variable. To get the value of the instance
257 variable, you should pass as 'returnValue' a pointer to an 'id';
258 the value will be copied there. Note that 'returnValue' is really
259 a 'void *', not a 'void **'. This function really works only with
260 instance variables of type 'id'; for other types of instance
261 variables, access directly the data at (char *)object +
262 ivar_getOffset (ivar). */
263 objc_EXPORT Ivar
object_getInstanceVariable (id object
, const char *name
, void **returnValue
);
265 /* Set the value of an instance variable. The value to set is passed
266 in 'newValue' (which really is an 'id', not a 'void *'). The
267 function returns the instance variable. This function really works
268 only with instance variables of type 'id'; for other types of
269 instance variables, access directly the data at (char *)object +
270 ivar_getOffset (ivar). */
271 objc_EXPORT Ivar
object_setInstanceVariable (id object
, const char *name
, void *newValue
);
273 /* Get the value of an instance variable of type 'id' of the object
274 'object'. This is faster than object_getInstanceVariable if you
275 already have the instance variable because it avoids the expensive
276 call to class_getInstanceVariable that is done by
277 object_getInstanceVariable. */
278 objc_EXPORT id
object_getIvar (id object
, Ivar variable
);
280 /* Set the value of an instance variable of type 'id' of the object
281 'object'. This is faster than object_setInstanceVariable if you
282 already have the instance variable because it avoids the expensive
283 call to class_getInstanceVariable that is done by
284 object_setInstanceVariable. */
285 objc_EXPORT
void object_setIvar (id object
, Ivar variable
, id value
);
287 /* Return the name of the instance variable. Return NULL if
288 'variable' is NULL. */
289 objc_EXPORT
const char * ivar_getName (Ivar variable
);
291 /* Return the offset of the instance variable from the start of the
292 object data. Return 0 if 'variable' is NULL. */
293 objc_EXPORT
ptrdiff_t ivar_getOffset (Ivar variable
);
295 /* Return the type encoding of the variable. Return NULL if
296 'variable' is NULL. */
297 objc_EXPORT
const char * ivar_getTypeEncoding (Ivar variable
);
299 /* Return all the instance variables of the class. The return value
300 of the function is a pointer to an area, allocated with malloc(),
301 that contains all the instance variables of the class. It does not
302 include instance variables of superclasses. The list is terminated
303 by NULL. Optionally, if you pass a non-NULL
304 'numberOfReturnedIvars' pointer, the unsigned int that it points to
305 will be filled with the number of instance variables returned. */
306 objc_EXPORT Ivar
* class_copyIvarList (Class class_
, unsigned int *numberOfReturnedIvars
);
308 /* Return the name of the property. Return NULL if 'property' is
310 objc_EXPORT
const char * property_getName (Property property
);
312 /* Return the attributes of the property as a string. Return NULL if
313 'property' is NULL. */
314 objc_EXPORT
const char * property_getAttributes (Property property
);
316 /* Return the property with name 'propertyName' of the class 'class_'.
317 This function returns NULL if the required property can not be
318 found. Return NULL if 'class_' or 'propertyName' is NULL.
320 Note that the traditional ABI does not store the list of properties
321 of a class in a compiled module, so the traditional ABI will always
323 objc_EXPORT Property
class_getProperty (Class class_
, const char *propertyName
);
325 /* Return all the properties of the class. The return value
326 of the function is a pointer to an area, allocated with malloc(),
327 that contains all the properties of the class. It does not
328 include properties of superclasses. The list is terminated
329 by NULL. Optionally, if you pass a non-NULL
330 'numberOfReturnedIvars' pointer, the unsigned int that it points to
331 will be filled with the number of properties returned.
333 Note that the traditional ABI does not store the list of properties
334 of a class in a compiled module, so the traditional ABI will always
335 return an empty list. */
336 objc_EXPORT Property
* class_copyPropertyList
337 (Class class_
, unsigned int *numberOfReturnedProperties
);
340 /** Implementation: the following functions are in class.c. */
342 /* Compatibility Note: The Apple/NeXT runtime does not have
343 objc_get_unknown_class_handler and
344 objc_setGetUnknownClassHandler(). They provide functionality that
345 the traditional GNU Objective-C Runtime API used to provide via the
346 _objc_lookup_class hook. */
348 /* An 'objc_get_unknown_class_handler' function is used by
349 objc_getClass() to get a class that is currently unknown to the
350 compiler. You could use it for example to have the class loaded by
351 dynamically loading a library. 'class_name' is the name of the
352 class. The function should return the Class object if it manages to
353 load the class, and Nil if not. */
354 typedef Class (*objc_get_unknown_class_handler
)(const char *class_name
);
356 /* Sets a new handler function for getting unknown classes (to be used
357 by objc_getClass () and related), and returns the previous one.
358 This function is not safe to call in a multi-threaded environment
359 because other threads may be trying to use the get unknown class
360 handler while you change it! */
361 objc_get_unknown_class_handler
362 objc_setGetUnknownClassHandler (objc_get_unknown_class_handler new_handler
);
365 /* Return the class with name 'name', if it is already registered with
366 the runtime. If it is not registered, and
367 objc_setGetUnknownClassHandler() has been called to set a handler
368 for unknown classes, the handler is called to give it a chance to
369 load the class in some other way. If the class is not known to the
370 runtime and the handler is not set or returns Nil, objc_getClass()
372 objc_EXPORT Class
objc_getClass (const char *name
);
374 /* Return the class with name 'name', if it is already registered with
375 the runtime. Return Nil if not. This function does not call the
376 objc_get_unknown_class_handler function if the class is not
378 objc_EXPORT Class
objc_lookupClass (const char *name
);
380 /* Return the meta class associated to the class with name 'name', if
381 it is already registered with the runtime. First, it finds the
382 class using objc_getClass(). Then, it returns the associated meta
383 class. If the class could not be found using objc_getClass(),
385 objc_EXPORT Class
objc_getMetaClass (const char *name
);
387 /* This is identical to objc_getClass(), but if the class is not found,
388 it aborts the process instead of returning Nil. */
389 objc_EXPORT Class
objc_getRequiredClass (const char *name
);
391 /* If 'returnValue' is NULL, 'objc_getClassList' returns the number of
392 classes currently registered with the runtime. If 'returnValue' is
393 not NULL, it should be a (Class *) pointer to an area of memory
394 which can contain up to 'maxNumberOfClassesToReturn' Class records.
395 'objc_getClassList' will fill the area pointed to by 'returnValue'
396 with all the Classes registered with the runtime (or up to
397 maxNumberOfClassesToReturn if there are more than
398 maxNumberOfClassesToReturn). The function return value is the
399 number of classes actually returned in 'returnValue'. */
400 objc_EXPORT
int objc_getClassList (Class
*returnValue
, int maxNumberOfClassesToReturn
);
402 /* Compatibility Note: The Apple/NeXT runtime also has
404 Class objc_getFutureClass (const char *name);
405 void objc_setFutureClass (Class class_, const char *name);
407 the documentation is unclear on what they are supposed to do, and
408 the GNU Objective-C Runtime currently does not provide them. */
410 /* Return the name of the class 'class_', or the string "nil" if the
412 objc_EXPORT
const char * class_getName (Class class_
);
414 /* Return YES if 'class_' is a meta class, and NO if not. If 'class_'
415 is Nil, return NO. */
416 objc_EXPORT BOOL
class_isMetaClass (Class class_
);
418 /* Return the superclass of 'class_'. If 'class_' is Nil, or it is a root
421 TODO: It may be worth to define this inline, since it is usually
422 used in loops when traversing the class hierarchy. */
423 objc_EXPORT Class
class_getSuperclass (Class class_
);
425 /* Return the 'version' number of the class, which is an integer that
426 can be used to track changes in the class API, methods and
427 variables. If class_ is Nil, return 0. If class_ is not Nil, the
428 version is 0 unless class_setVersion() has been called to set a
431 Please note that internally the version is a long, but the API only
432 allows you to set and retrieve int values. */
433 objc_EXPORT
int class_getVersion (Class class_
);
435 /* Set the 'version' number of the class, which is an integer that can
436 be used to track changes in the class API, methods and variables.
437 If 'class_' is Nil, does nothing.
439 This is typically used internally by "Foundation" libraries such as
440 GNUstep Base to support serialization / deserialization of objects
441 that work across changes in the classes. If you are using such a
442 library, you probably want to use their versioning API, which may
443 be based on this one, but is integrated with the rest of the
446 Please note that internally the version is a long, but the API only
447 allows you to set and retrieve int values. */
448 objc_EXPORT
void class_setVersion (Class class_
, int version
);
450 /* Return the size in bytes (a byte is the size of a char) of an
451 instance of the class. If class_ is Nil, return 0; else it return
452 a non-zero number (since the 'isa' instance variable is required
454 objc_EXPORT
size_t class_getInstanceSize (Class class_
);
456 /* Change the implementation of the method. It also searches all
457 classes for any class implementing the method, and replaces the
458 existing implementation with the new one. For that to work,
459 'method' must be a method returned by class_getInstanceMethod() or
460 class_getClassMethod() as the matching is done by comparing the
461 pointers; in that case, only the implementation in the class is
462 modified. Return the previous implementation that has been
463 replaced. If method or implementation is NULL, do nothing and
466 method_setImplementation (Method method
, IMP implementation
);
468 /* Swap the implementation of two methods in a single, atomic
469 operation. This is equivalent to getting the implementation of
470 each method and then calling method_setImplementation() on the
471 other one. For this to work, the two methods must have been
472 returned by class_getInstanceMethod() or class_getClassMethod().
473 If 'method_a' or 'method_b' is NULL, do nothing. */
475 method_exchangeImplementations (Method method_a
, Method method_b
);
478 /** Implementation: the following functions are in sendmsg.c. */
480 /* Return the instance method with selector 'selector' of class
481 'class_', or NULL if the class (or one of its superclasses) does
482 not implement the method. Return NULL if class_ is Nil or selector
484 objc_EXPORT Method
class_getInstanceMethod (Class class_
, SEL selector
);
486 /* Return the class method with selector 'selector' of class 'class_',
487 or NULL if the class (or one of its superclasses) does not
488 implement the method. Return NULL if class_ is Nil or selector is
490 objc_EXPORT Method
class_getClassMethod (Class class_
, SEL selector
);
492 /* Return the IMP (pointer to the function implementing a method) for
493 the instance method with selector 'selector' in class 'class_'.
494 This is the same routine that is used while messaging, and should
495 be very fast. Note that you most likely would need to cast the
496 return function pointer to a function pointer with the appropriate
497 arguments and return type before calling it. To get a class
498 method, you can pass the meta-class as the class_ argument (ie, use
499 class_getMethodImplementation (object_getClass (class_),
500 selector)). Return NULL if class_ is Nil or selector is NULL. */
501 objc_EXPORT IMP
class_getMethodImplementation (Class class_
, SEL selector
);
503 /* Compatibility Note: the Apple/NeXT runtime has the function
504 class_getMethodImplementation_stret () which currently does not
505 exist on the GNU runtime because the messaging implementation is
508 /* Return YES if class 'class_' has an instance method implementing
509 selector 'selector', and NO if not. Return NO if class_ is Nil or
510 selector is NULL. If you need to check a class method, use the
511 meta-class as the class_ argument (ie, use class_respondsToSelector
512 (object_getClass (class_), selector)). */
513 objc_EXPORT BOOL
class_respondsToSelector (Class class_
, SEL selector
);
516 /** Implementation: the following functions are in methods.c. */
518 /* Return the selector for method 'method'. Return NULL if 'method'
521 This function is misnamed; it should be called
522 'method_getSelector'. To get the actual name, get the selector,
523 then the name from the selector (ie, use sel_getName
524 (method_getName (method))). */
525 objc_EXPORT SEL
method_getName (Method method
);
527 /* Return the IMP of the method. Return NULL if 'method' is NULL. */
528 objc_EXPORT IMP
method_getImplementation (Method method
);
530 /* Return the type encoding of the method. Return NULL if 'method' is
532 objc_EXPORT
const char * method_getTypeEncoding (Method method
);
534 /* Return a method description for the method. Return NULL if
536 objc_EXPORT
struct objc_method_description
* method_getDescription (Method method
);
538 /* Return all the instance methods of the class. The return value of
539 the function is a pointer to an area, allocated with malloc(), that
540 contains all the instance methods of the class. It does not
541 include instance methods of superclasses. The list is terminated
542 by NULL. Optionally, if you pass a non-NULL
543 'numberOfReturnedMethods' pointer, the unsigned int that it points
544 to will be filled with the number of instance methods returned. To
545 get the list of class methods, pass the meta-class in the 'class_'
546 argument, (ie, use class_copyMethodList (object_getClass (class_),
547 &numberOfReturnedMethods)). */
548 objc_EXPORT Method
* class_copyMethodList (Class class_
, unsigned int *numberOfReturnedMethods
);
551 /** Implementation: the following functions are in encoding.c. */
553 /* Return the number of arguments that the method 'method' expects.
554 Note that all methods need two implicit arguments ('self' for the
555 receiver, and '_cmd' for the selector). Return 0 if 'method' is
557 objc_EXPORT
unsigned int method_getNumberOfArguments (Method method
);
559 /* Return the string encoding for the return type of method 'method'.
560 The string is a standard zero-terminated string in an area of
561 memory allocated with malloc(); you should free it with free() when
562 you finish using it. Return an empty string if method is NULL. */
563 objc_EXPORT
char * method_copyReturnType (Method method
);
565 /* Return the string encoding for the argument type of method
566 'method', argument number 'argumentNumber' ('argumentNumber' is 0
567 for self, 1 for _cmd, and 2 or more for the additional arguments if
568 any). The string is a standard zero-terminated string in an area
569 of memory allocated with malloc(); you should free it with free()
570 when you finish using it. Return an empty string if method is NULL
571 or if 'argumentNumber' refers to a non-existing argument. */
572 objc_EXPORT
char * method_copyArgumentType (Method method
, unsigned int argumentNumber
);
574 /* Return the string encoding for the return type of method 'method'.
575 The string is returned by copying it into the supplied
576 'returnValue' string, which is of size 'returnValueSize'. No more
577 than 'returnValueSize' characters are copied; if the encoding is
578 smaller than 'returnValueSize', the rest of 'returnValue' is filled
579 with zeros. If it is bigger, it is truncated (and would not be
580 zero-terminated). You should supply a big enough
581 'returnValueSize'. If the method is NULL, returnValue is set to a
583 objc_EXPORT
void method_getReturnType (Method method
, char *returnValue
,
584 size_t returnValueSize
);
586 /* Return the string encoding for the argument type of method
587 'method', argument number 'argumentNumber' ('argumentNumber' is 0
588 for self, 1 for _cmd, and 2 or more for the additional arguments if
589 any). The string is returned by copying it into the supplied
590 'returnValue' string, which is of size 'returnValueSize'. No more
591 than 'returnValueSize' characters are copied; if the encoding is
592 smaller than 'returnValueSize', the rest of 'returnValue' is filled
593 with zeros. If it is bigger, it is truncated (and would not be
594 zero-terminated). You should supply a big enough
595 'returnValueSize'. If the method is NULL, returnValue is set to a
597 objc_EXPORT
void method_getArgumentType (Method method
, unsigned int argumentNumber
,
598 char *returnValue
, size_t returnValueSize
);
601 /** Implementation: the following functions are in protocols.c. */
603 /* Return the protocol with name 'name', or nil if it the protocol is
604 not known to the runtime. */
605 objc_EXPORT Protocol
*objc_getProtocol (const char *name
);
607 /* Return all the protocols known to the runtime. The return value of
608 the function is a pointer to an area, allocated with malloc(), that
609 contains all the protocols known to the runtime; the list is
610 terminated by NULL. You should free this area using free() once
611 you no longer need it. Optionally, if you pass a non-NULL
612 'numberOfReturnedProtocols' pointer, the unsigned int that it
613 points to will be filled with the number of protocols returned. If
614 there are no protocols known to the runtime, NULL is returned. */
615 objc_EXPORT Protocol
**objc_copyProtocolList (unsigned int *numberOfReturnedProtocols
);
617 /* Add a protocol to a class, and return YES if it was done
618 succesfully, and NO if not. At the moment, NO should only happen
619 if class_ or protocol are nil, if the protocol is not a Protocol
620 object or if the class already conforms to the protocol. */
621 objc_EXPORT BOOL
class_addProtocol (Class class_
, Protocol
*protocol
);
623 /* Return YES if the class 'class_' conforms to Protocol 'protocol',
625 objc_EXPORT BOOL
class_conformsToProtocol (Class class_
, Protocol
*protocol
);
627 /* Return all the protocols that the class conforms to. The return
628 value of the function is a pointer to an area, allocated with
629 malloc(), that contains all the protocols formally adopted by the
630 class. It does not include protocols adopted by superclasses. The
631 list is terminated by NULL. Optionally, if you pass a non-NULL
632 'numberOfReturnedProtocols' pointer, the unsigned int that it
633 points to will be filled with the number of protocols returned. */
634 objc_EXPORT Protocol
**class_copyProtocolList (Class class_
, unsigned int *numberOfReturnedProtocols
);
636 /* Return YES if protocol 'protocol' conforms to protocol
637 'anotherProtocol', and NO if not. Note that if one of the two
638 protocols is nil, it returns NO. */
639 objc_EXPORT BOOL
protocol_conformsToProtocol (Protocol
*protocol
, Protocol
*anotherProtocol
);
641 /* Return YES if protocol 'protocol' is the same as protocol
642 'anotherProtocol', and 'NO' if not. Note that it returns YES if
643 the two protocols are both nil. */
644 objc_EXPORT BOOL
protocol_isEqual (Protocol
*protocol
, Protocol
*anotherProtocol
);
646 /* Return the name of protocol 'protocol'. If 'protocol' is nil or is
647 not a Protocol, return NULL. */
648 objc_EXPORT
const char *protocol_getName (Protocol
*protocol
);
650 /* Return the method description for the method with selector
651 'selector' in protocol 'protocol'; if 'requiredMethod' is YES, the
652 function searches the list of required methods; if NO, the list of
653 optional methods. If 'instanceMethod' is YES, the function search
654 for an instance method; if NO, for a class method. If there is no
655 matching method, an objc_method_description structure with both
656 name and types set to NULL is returned. This function will only
657 find methods that are directly declared in the protocol itself, not
658 in other protocols that this protocol adopts.
660 Note that the traditional ABI does not store the list of optional
661 methods of a protocol in a compiled module, so the traditional ABI
662 will always return (NULL, NULL) when requiredMethod == NO. */
663 objc_EXPORT
struct objc_method_description
protocol_getMethodDescription (Protocol
*protocol
,
666 BOOL instanceMethod
);
668 /* Return the method descriptions of all the methods of the protocol.
669 The return value of the function is a pointer to an area, allocated
670 with malloc(), that contains all the method descriptions of the
671 methods of the protocol. It does not recursively include methods
672 of the protocols adopted by this protocol. The list is terminated
673 by a NULL objc_method_description (one with both fields set to
674 NULL). Optionally, if you pass a non-NULL
675 'numberOfReturnedMethods' pointer, the unsigned int that it points
676 to will be filled with the number of properties returned.
678 Note that the traditional ABI does not store the list of optional
679 methods of a protocol in a compiled module, so the traditional ABI
680 will always return an empty list if requiredMethod is set to
682 objc_EXPORT
struct objc_method_description
*protocol_copyMethodDescriptionList (Protocol
*protocol
,
685 unsigned int *numberOfReturnedMethods
);
687 /* Return the property with name 'propertyName' of the protocol
688 'protocol'. If 'requiredProperty' is YES, the function searches
689 the list of required properties; if NO, the list of optional
690 properties. If 'instanceProperty' is YES, the function searches
691 the list of instance properties; if NO, the list of class
692 properties. At the moment, optional properties and class
693 properties are not part of the Objective-C language, so both
694 'requiredProperty' and 'instanceProperty' should be set to YES.
695 This function returns NULL if the required property can not be
698 Note that the traditional ABI does not store the list of properties
699 of a protocol in a compiled module, so the traditional ABI will
700 always return NULL. */
701 objc_EXPORT Property
protocol_getProperty (Protocol
*protocol
, const char *propertyName
,
702 BOOL requiredProperty
, BOOL instanceProperty
);
704 /* Return all the properties of the protocol. The return value of the
705 function is a pointer to an area, allocated with malloc(), that
706 contains all the properties of the protocol. It does not
707 recursively include properties of the protocols adopted by this
708 protocol. The list is terminated by NULL. Optionally, if you pass
709 a non-NULL 'numberOfReturnedProperties' pointer, the unsigned int
710 that it points to will be filled with the number of properties
713 Note that the traditional ABI does not store the list of properties
714 of a protocol in a compiled module, so the traditional ABI will
715 always return NULL and store 0 in numberOfReturnedProperties. */
716 objc_EXPORT Property
*protocol_copyPropertyList (Protocol
*protocol
, unsigned int *numberOfReturnedProperties
);
718 /* Return all the protocols that the protocol conforms to. The return
719 value of the function is a pointer to an area, allocated with
720 malloc(), that contains all the protocols formally adopted by the
721 protocol. It does not recursively include protocols adopted by the
722 protocols adopted by this protocol. The list is terminated by
723 NULL. Optionally, if you pass a non-NULL
724 'numberOfReturnedProtocols' pointer, the unsigned int that it
725 points to will be filled with the number of protocols returned. */
726 objc_EXPORT Protocol
**protocol_copyProtocolList (Protocol
*protocol
, unsigned int *numberOfReturnedProtocols
);
729 /* TODO: Add all the other functions in the API. */
732 /** Implementation: the following functions are in objc-foreach.c. */
734 /* 'objc_enumerationMutation()' is called when a collection is
735 mutated while being "fast enumerated". That is a hard error, and
736 objc_enumerationMutation is called to deal with it. 'collection'
737 is the collection object that was mutated during an enumeration.
739 objc_enumerationMutation() will invoke the mutation handler if any
740 is set. Then, it will abort the program.
742 Compatibility note: the Apple runtime will not abort the program
743 after calling the mutation handler. */
744 objc_EXPORT
void objc_enumerationMutation (id collection
);
746 /* 'objc_set_enumeration_mutation_handler' can be used to set a
747 function that will be called (instead of aborting) when a fast
748 enumeration is mutated during enumeration. The handler will be
749 called with the 'collection' being mutated as the only argument and
750 it should not return; it should either exit the program, or could
751 throw an exception. The recommended implementation is to throw an
752 exception - the user can then use exception handlers to deal with
755 This function is not thread safe (other threads may be trying to
756 invoke the enumeration mutation handler while you are changing it!)
757 and should be called during during the program initialization
758 before threads are started. It is mostly reserved for "Foundation"
759 libraries; in the case of GNUstep, GNUstep Base may be using this
760 function to improve the standard enumeration mutation handling.
761 You probably shouldn't use this function unless you are writing
762 your own Foundation library. */
763 objc_EXPORT
void objc_setEnumerationMutationHandler (void (*handler
)(id
));
765 /* This structure (used during fast enumeration) is automatically
766 defined by the compiler (it is as if this definition was always
767 included in all Objective-C files). Note that it is usually
768 defined again with the name of NSFastEnumeration by "Foundation"
769 libraries such as GNUstep Base. And if NSFastEnumeration is
770 defined, the compiler will use it instead of
771 __objcFastEnumerationState when doing fast enumeration. */
773 struct __objcFastEnumerationState
777 unsigned long *mutationsPtr;
778 unsigned long extra[5];
783 /** Implementation: the following functions are in memory.c. */
785 /* Traditional GNU Objective-C Runtime functions that are used for
786 memory allocation and disposal. These functions are used in the
787 same way as you use malloc, realloc, calloc and free and make sure
788 that memory allocation works properly with the garbage
791 Compatibility Note: these functions are not available with the
792 Apple/NeXT runtime. */
794 objc_EXPORT
void *objc_malloc(size_t size
);
796 /* FIXME: Shouldn't the following be called objc_malloc_atomic ? The
797 GC function is GC_malloc_atomic() which makes sense.
799 objc_EXPORT
void *objc_atomic_malloc(size_t size
);
801 objc_EXPORT
void *objc_realloc(void *mem
, size_t size
);
803 objc_EXPORT
void *objc_calloc(size_t nelem
, size_t size
);
805 objc_EXPORT
void objc_free(void *mem
);
808 /** Implementation: the following functions are in encoding.c. */
810 /* Traditional GNU Objective-C Runtime functions that are currently
811 used to implement method forwarding.
813 Compatibility Note: these functions are not available with the
814 Apple/NeXT runtime. */
816 /* Return the size of a variable which has the specified 'type'
818 int objc_sizeof_type (const char *type
);
820 /* Return the align of a variable which has the specified 'type'
822 int objc_alignof_type (const char *type
);
824 /* Return the aligned size of a variable which has the specified
825 'type' encoding. The aligned size is the size rounded up to the
826 nearest alignment. */
827 int objc_aligned_size (const char *type
);
829 /* Return the promoted size of a variable which has the specified
830 'type' encoding. This is the size rounded up to the nearest
831 integral of the wordsize, taken to be the size of a void *. */
832 int objc_promoted_size (const char *type
);
835 /* The following functions are used when parsing the type encoding of
836 methods, to skip over parts that are ignored. They take as
837 argument a pointer to a location inside the type encoding of a
838 method (which is a string) and return a new pointer, pointing to a
839 new location inside the string after having skipped the unwanted
842 /* Skip some type qualifiers (_C_CONST, _C_IN, etc). These may
843 eventually precede typespecs occurring in method prototype
845 const char *objc_skip_type_qualifiers (const char *type
);
847 /* Skip one typespec element (_C_CLASS, _C_SEL, etc). If the typespec
848 is prepended by type qualifiers, these are skipped as well. */
849 const char *objc_skip_typespec (const char *type
);
851 /* Skip an offset. */
852 const char *objc_skip_offset (const char *type
);
854 /* Skip an argument specification (ie, skipping a typespec, which may
855 include qualifiers, and an offset too). */
856 const char *objc_skip_argspec (const char *type
);
858 /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type'
859 (stopping at the first non-type qualifier found) and return an
860 unsigned int which is the logical OR of all the corresponding flags
861 (_F_CONST, _F_IN etc). */
862 unsigned objc_get_type_qualifiers (const char *type
);
865 /* Note that the following functions work for very simple structures,
866 but get easily confused by more complicated ones (for example,
867 containing vectors). A better solution is required.
870 /* The following three functions can be used to determine how a
871 structure is laid out by the compiler. For example:
873 struct objc_struct_layout layout;
876 objc_layout_structure (type, &layout);
877 while (objc_layout_structure_next_member (&layout))
882 objc_layout_structure_get_info (&layout, &position, &align, &type);
883 printf ("element %d has offset %d, alignment %d\n",
884 i++, position, align);
887 These functions are used by objc_sizeof_type and objc_alignof_type
888 functions to compute the size and alignment of structures. The
889 previous method of computing the size and alignment of a structure
890 was not working on some architectures, particulary on AIX, and in
891 the presence of bitfields inside the structure. */
892 struct objc_struct_layout
894 const char *original_type
;
896 const char *prev_type
;
897 unsigned int record_size
;
898 unsigned int record_align
;
901 void objc_layout_structure (const char *type
,
902 struct objc_struct_layout
*layout
);
903 BOOL
objc_layout_structure_next_member (struct objc_struct_layout
*layout
);
904 void objc_layout_finish_structure (struct objc_struct_layout
*layout
,
906 unsigned int *align
);
907 void objc_layout_structure_get_info (struct objc_struct_layout
*layout
,
908 unsigned int *offset
,