1 /* GNU Objective-C Runtime API - Modern API
2 Copyright (C) 2010-2023 Free Software Foundation, Inc.
3 Contributed by Nicola Pero <nicola.pero@meta-innovation.com>
4
5 This file is part of GCC.
6
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
10 later version.
11
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.
16
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.
20
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/>. */
25
26 #ifndef __objc_runtime_INCLUDE_GNU
27 #define __objc_runtime_INCLUDE_GNU
28
29 /*
30 This file declares the "modern" GNU Objective-C Runtime API.
31
32 This API replaced the "traditional" GNU Objective-C Runtime API
33 (which used to be declared in objc/objc-api.h) which is the one
34 supported by older versions of the GNU Objective-C Runtime. The
35 "modern" API is very similar to the API used by the modern
36 Apple/NeXT runtime.
37 */
38 #include "objc.h"
39 #include "objc-decls.h"
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif /* __cplusplus */
44
45 /* An 'Ivar' represents an instance variable. It holds information
46 about the name, type and offset of the instance variable. */
47 typedef struct objc_ivar *Ivar;
48
49 /* A 'Property' represents a property. It holds information about the
50 name of the property, and its attributes.
51
52 Compatibility Note: the Apple/NeXT runtime defines this as
53 objc_property_t, so we define it that way as well, but obviously
54 Property is the right name. */
55 typedef struct objc_property *Property;
56 typedef struct objc_property *objc_property_t;
57
58 /* A 'Method' represents a method. It holds information about the
59 name, types and the IMP of the method. */
60 typedef struct objc_method *Method;
61
62 /* A 'Category' represents a category. It holds information about the
63 name of the category, the class it belongs to, and the methods,
64 protocols and such like provided by the category. */
65 typedef struct objc_category *Category;
66
67 /* 'Protocol' is defined in objc/objc.h (which is included by this
68 file). */
69
70 /* Method descriptor returned by introspective Object methods. At the
71 moment, this is really just the first part of the more complete
72 objc_method structure used internally by the runtime. (PS: In the
73 GNU Objective-C Runtime, selectors already include a type, so an
74 objc_method_description does not add much to a SEL. But in other
75 runtimes, that is not the case, which is why
76 objc_method_description exists). */
77 struct objc_method_description
78 {
79 SEL name; /* Selector (name and signature) */
80 char *types; /* Type encoding */
81 };
82
83 /* The following are used in encode strings to describe the type of
84 Ivars and Methods. */
85 #define _C_ID '@'
86 #define _C_CLASS '#'
87 #define _C_SEL ':'
88 #define _C_CHR 'c'
89 #define _C_UCHR 'C'
90 #define _C_SHT 's'
91 #define _C_USHT 'S'
92 #define _C_INT 'i'
93 #define _C_UINT 'I'
94 #define _C_LNG 'l'
95 #define _C_ULNG 'L'
96 #define _C_LNG_LNG 'q'
97 #define _C_ULNG_LNG 'Q'
98 #define _C_FLT 'f'
99 #define _C_DBL 'd'
100 #define _C_LNG_DBL 'D'
101 #define _C_BFLD 'b'
102 #define _C_BOOL 'B'
103 #define _C_VOID 'v'
104 #define _C_UNDEF '?'
105 #define _C_PTR '^'
106 #define _C_CHARPTR '*'
107 #define _C_ARY_B '['
108 #define _C_ARY_E ']'
109 #define _C_UNION_B '('
110 #define _C_UNION_E ')'
111 #define _C_STRUCT_B '{'
112 #define _C_STRUCT_E '}'
113 #define _C_VECTOR '!'
114 #define _C_COMPLEX 'j'
115
116 /* _C_ATOM is never generated by the compiler. You can treat it as
117 equivalent to "*". */
118 #define _C_ATOM '%'
119
120 /* The following are used in encode strings to describe some
121 qualifiers of method and ivar types. */
122 #define _C_CONST 'r'
123 #define _C_IN 'n'
124 #define _C_INOUT 'N'
125 #define _C_OUT 'o'
126 #define _C_BYCOPY 'O'
127 #define _C_BYREF 'R'
128 #define _C_ONEWAY 'V'
129 #define _C_GCINVISIBLE '|'
130
131 /* The same when used as flags. */
132 #define _F_CONST 0x01
133 #define _F_IN 0x01
134 #define _F_OUT 0x02
135 #define _F_INOUT 0x03
136 #define _F_BYCOPY 0x04
137 #define _F_BYREF 0x08
138 #define _F_ONEWAY 0x10
139 #define _F_GCINVISIBLE 0x20
140
141
142 /** Implementation: the following functions are defined inline. */
143
144 /* Return the class of 'object', or Nil if the object is nil. If
145 'object' is a class, the meta class is returned; if 'object' is a
146 meta class, the root meta class is returned (note that this is
147 different from the traditional GNU Objective-C Runtime API function
148 object_get_class(), which for a meta class would return the meta
149 class itself). This function is inline, so it is really fast and
150 should be used instead of accessing object->class_pointer
151 directly. */
152 static inline Class
153 object_getClass (id object)
154 {
155 if (object != nil)
156 return object->class_pointer;
157 else
158 return Nil;
159 }
160
161
162 /** Implementation: the following functions are in selector.c. */
163
164 /* Return the name of a given selector. If 'selector' is NULL, return
165 "<null selector>". */
166 objc_EXPORT const char *sel_getName (SEL selector);
167
168 /* Return the type of a given selector. Return NULL if selector is
169 NULL.
170
171 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
172 so it does not have this function, which is specific to the GNU
173 Runtime. */
174 objc_EXPORT const char *sel_getTypeEncoding (SEL selector);
175
176 /* This is the same as sel_registerName (). Please use
177 sel_registerName () instead. */
178 objc_EXPORT SEL sel_getUid (const char *name);
179
180 /* Register a selector with a given name (but unspecified types). If
181 you know the types, it is better to call sel_registerTypedName().
182 If a selector with this name and no types already exists, it is
183 returned. Note that this function should really be called
184 'objc_registerSelector'. Return NULL if 'name' is NULL. */
185 objc_EXPORT SEL sel_registerName (const char *name);
186
187 /* Register a selector with a given name and types. If a selector
188 with this name and types already exists, it is returned. Note that
189 this function should really be called 'objc_registerTypedSelector',
190 and it's called 'sel_registerTypedName' only for consistency with
191 'sel_registerName'. Return NULL if 'name' is NULL.
192
193 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
194 so it does not have this function, which is specific to the GNU
195 Runtime. */
196 objc_EXPORT SEL sel_registerTypedName (const char *name, const char *type);
197
198 /* Return YES if first_selector is the same as second_selector, and NO
199 if not. */
200 objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector);
201
202 /* Return all the selectors with the supplied name. In the GNU
203 runtime, selectors are typed and there may be multiple selectors
204 with the same name but a different type. The return value of the
205 function is a pointer to an area, allocated with malloc(), that
206 contains all the selectors with the supplier name known to the
207 runtime. The list is terminated by NULL. Optionally, if you pass
208 a non-NULL 'numberOfReturnedSelectors' pointer, the unsigned int
209 that it points to will be filled with the number of selectors
210 returned.
211
212 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
213 so it does not have this function, which is specific to the GNU
214 Runtime. */
215 objc_EXPORT SEL * sel_copyTypedSelectorList (const char *name,
216 unsigned int *numberOfReturnedSelectors);
217
218 /* Return a selector with name 'name' and a non-zero type encoding, if
219 there is a single selector with a type, and with that name,
220 registered with the runtime. If there is no such selector, or if
221 there are multiple selectors with the same name but conflicting
222 types, NULL is returned. Return NULL if 'name' is NULL.
223
224 This is useful if you have the name of the selector, and would
225 really like to get a selector for it that includes the type
226 encoding. Unfortunately, if the program contains multiple selector
227 with the same name but different types, sel_getTypedSelector cannot
228 possibly know which one you need, and so will return NULL.
229
230 Compatibility Note: the Apple/NeXT runtime has untyped selectors,
231 so it does not have this function, which is specific to the GNU
232 Runtime. */
233 objc_EXPORT SEL sel_getTypedSelector (const char *name);
234
235
236 /** Implementation: the following functions are in objects.c. */
237
238 /* Create an instance of class 'class_', adding extraBytes to the size
239 of the returned object. This method allocates the appropriate
240 amount of memory for the instance, initializes it to zero, then
241 calls all the C++ constructors on appropriate C++ instance
242 variables of the instance (if any) (TODO: The C++ constructors bit
243 is not implemented yet). */
244 objc_EXPORT id class_createInstance (Class class_, size_t extraBytes);
245
246 /* Copy an object and return the copy. extraBytes should be identical
247 to the extraBytes parameter that was passed when creating the
248 original object. */
249 objc_EXPORT id object_copy (id object, size_t extraBytes);
250
251 /* Dispose of an object. This method calls the appropriate C++
252 destructors on appropriate C++ instance variables of the instance
253 (if any) (TODO: This is not implemented yet), then frees the memory
254 for the instance. */
255 objc_EXPORT id object_dispose (id object);
256
257 /* Return the name of the class of 'object'. If 'object' is 'nil',
258 returns "Nil". */
259 objc_EXPORT const char * object_getClassName (id object);
260
261 /* Change the class of object to be class_. Return the previous class
262 of object. This is currently not really thread-safe. */
263 objc_EXPORT Class object_setClass (id object, Class class_);
264
265
266 /** Implementation: the following functions are in ivars.c. */
267
268 /* Return an instance variable given the class and the instance
269 variable name. This is an expensive function to call, so try to
270 reuse the returned Ivar if you can. */
271 objc_EXPORT Ivar class_getInstanceVariable (Class class_, const char *name);
272
273 /* Return a class variable given the class and the class variable
274 name. This is an expensive function to call, so try to reuse the
275 returned Ivar if you can.
276
277 This function always returns NULL since class variables are
278 currently unavailable in Objective-C. */
279 objc_EXPORT Ivar class_getClassVariable (Class class_, const char *name);
280
281 /* If the object was created in class_createInstance() with some
282 extraBytes, returns a pointer to them. If it was not, then the
283 returned pointer may make no sense. */
284 objc_EXPORT void * object_getIndexedIvars (id object);
285
286 /* Get the value of an instance variable of type 'id'. The function
287 returns the instance variable. To get the value of the instance
288 variable, you should pass as 'returnValue' a pointer to an 'id';
289 the value will be copied there. Note that 'returnValue' is really
290 a 'void *', not a 'void **'. This function really works only with
291 instance variables of type 'id'; for other types of instance
292 variables, access directly the data at (char *)object +
293 ivar_getOffset (ivar). */
294 objc_EXPORT Ivar object_getInstanceVariable (id object, const char *name, void **returnValue);
295
296 /* Set the value of an instance variable. The value to set is passed
297 in 'newValue' (which really is an 'id', not a 'void *'). The
298 function returns the instance variable. This function really works
299 only with instance variables of type 'id'; for other types of
300 instance variables, access directly the data at (char *)object +
301 ivar_getOffset (ivar). */
302 objc_EXPORT Ivar object_setInstanceVariable (id object, const char *name, void *newValue);
303
304 /* Get the value of an instance variable of type 'id' of the object
305 'object'. This is faster than object_getInstanceVariable if you
306 already have the instance variable because it avoids the expensive
307 call to class_getInstanceVariable that is done by
308 object_getInstanceVariable. */
309 objc_EXPORT id object_getIvar (id object, Ivar variable);
310
311 /* Set the value of an instance variable of type 'id' of the object
312 'object'. This is faster than object_setInstanceVariable if you
313 already have the instance variable because it avoids the expensive
314 call to class_getInstanceVariable that is done by
315 object_setInstanceVariable. */
316 objc_EXPORT void object_setIvar (id object, Ivar variable, id value);
317
318 /* Return the name of the instance variable. Return NULL if
319 'variable' is NULL. */
320 objc_EXPORT const char * ivar_getName (Ivar variable);
321
322 /* Return the offset of the instance variable from the start of the
323 object data. Return 0 if 'variable' is NULL. */
324 objc_EXPORT ptrdiff_t ivar_getOffset (Ivar variable);
325
326 /* Return the type encoding of the variable. Return NULL if
327 'variable' is NULL. */
328 objc_EXPORT const char * ivar_getTypeEncoding (Ivar variable);
329
330 /* Return all the instance variables of the class. The return value
331 of the function is a pointer to an area, allocated with malloc(),
332 that contains all the instance variables of the class. It does not
333 include instance variables of superclasses. The list is terminated
334 by NULL. Optionally, if you pass a non-NULL
335 'numberOfReturnedIvars' pointer, the unsigned int that it points to
336 will be filled with the number of instance variables returned.
337 Return NULL for classes still in construction (ie, allocated using
338 objc_allocatedClassPair() but not yet registered with the runtime
339 using objc_registerClassPair()). */
340 objc_EXPORT Ivar * class_copyIvarList (Class class_, unsigned int *numberOfReturnedIvars);
341
342 /* Add an instance variable with name 'ivar_name' to class 'class_',
343 where 'class_' is a class in construction that has been created
344 using objc_allocateClassPair() and has not been registered with the
345 runtime using objc_registerClassPair() yet. You cannot add
346 instance variables to classes already registered with the runtime.
347 'size' is the size of the instance variable, 'log_2_of_alignment'
348 the alignment as a power of 2 (so 0 means alignment to a 1 byte
349 boundary, 1 means alignment to a 2 byte boundary, 2 means alignment
350 to a 4 byte boundary, etc), and 'type' the type encoding of the
351 variable type. You can use sizeof(), log2(__alignof__()) and
352 @encode() to determine the right 'size', 'alignment' and 'type' for
353 your instance variable. For example, to add an instance variable
354 name "my_variable" and of type 'id', you can use:
355
356 class_addIvar (class, "my_variable", sizeof (id), log2 ( __alignof__ (id)),
357 @encode (id));
358
359 Return YES if the variable was added, and NO if not. In
360 particular, return NO if 'class_' is Nil, or a meta-class or a
361 class not in construction. Return Nil also if 'ivar_name' or
362 'type' is NULL, or 'size' is 0.
363 */
364 objc_EXPORT BOOL class_addIvar (Class class_, const char * ivar_name, size_t size,
365 unsigned char log_2_of_alignment, const char *type);
366
367 /* Return the name of the property. Return NULL if 'property' is
368 NULL. */
369 objc_EXPORT const char * property_getName (Property property);
370
371 /* Return the attributes of the property as a string. Return NULL if
372 'property' is NULL. */
373 objc_EXPORT const char * property_getAttributes (Property property);
374
375 /* Return the property with name 'propertyName' of the class 'class_'.
376 This function returns NULL if the required property cannot be
377 found. Return NULL if 'class_' or 'propertyName' is NULL.
378
379 Note that the traditional ABI does not store the list of properties
380 of a class in a compiled module, so the traditional ABI will always
381 return NULL. */
382 objc_EXPORT Property class_getProperty (Class class_, const char *propertyName);
383
384 /* Return all the properties of the class. The return value
385 of the function is a pointer to an area, allocated with malloc(),
386 that contains all the properties of the class. It does not
387 include properties of superclasses. The list is terminated
388 by NULL. Optionally, if you pass a non-NULL
389 'numberOfReturnedIvars' pointer, the unsigned int that it points to
390 will be filled with the number of properties returned.
391
392 Note that the traditional ABI does not store the list of properties
393 of a class in a compiled module, so the traditional ABI will always
394 return an empty list. */
395 objc_EXPORT Property * class_copyPropertyList
396 (Class class_, unsigned int *numberOfReturnedProperties);
397
398 /* Return the ivar layout for class 'class_'.
399
400 At the moment this function always returns NULL. */
401 objc_EXPORT const char * class_getIvarLayout (Class class_);
402
403 /* Return the weak ivar layout for class 'class_'.
404
405 At the moment this function always returns NULL. */
406 objc_EXPORT const char * class_getWeakIvarLayout (Class class_);
407
408 /* Set the ivar layout for class 'class_'.
409
410 At the moment, this function does nothing. */
411 objc_EXPORT void class_setIvarLayout (Class class_, const char *layout);
412
413 /* Set the weak ivar layout for class 'class_'.
414
415 At the moment, this function does nothing. With the GNU runtime,
416 you should use class_ivar_set_gcinvisible () to hide variables from
417 the Garbage Collector. */
418 objc_EXPORT void class_setWeakIvarLayout (Class class_, const char *layout);
419
420
421 /** Implementation: the following functions are in class.c. */
422
423 /* Compatibility Note: The Apple/NeXT runtime does not have
424 objc_get_unknown_class_handler and
425 objc_setGetUnknownClassHandler(). They provide functionality that
426 the traditional GNU Objective-C Runtime API used to provide via the
427 _objc_lookup_class hook. */
428
429 /* An 'objc_get_unknown_class_handler' function is used by
430 objc_getClass() to get a class that is currently unknown to the
431 compiler. You could use it for example to have the class loaded by
432 dynamically loading a library. 'class_name' is the name of the
433 class. The function should return the Class object if it manages to
434 load the class, and Nil if not. */
435 typedef Class (*objc_get_unknown_class_handler)(const char *class_name);
436
437 /* Sets a new handler function for getting unknown classes (to be used
438 by objc_getClass () and related), and returns the previous one.
439 This function is not safe to call in a multi-threaded environment
440 because other threads may be trying to use the get unknown class
441 handler while you change it! */
442 objc_EXPORT
443 objc_get_unknown_class_handler
444 objc_setGetUnknownClassHandler (objc_get_unknown_class_handler new_handler);
445
446 /* Return the class with name 'name', if it is already registered with
447 the runtime. If it is not registered, and
448 objc_setGetUnknownClassHandler() has been called to set a handler
449 for unknown classes, the handler is called to give it a chance to
450 load the class in some other way. If the class is not known to the
451 runtime and the handler is not set or returns Nil, objc_getClass()
452 returns Nil. */
453 objc_EXPORT Class objc_getClass (const char *name);
454
455 /* Return the class with name 'name', if it is already registered with
456 the runtime. Return Nil if not. This function does not call the
457 objc_get_unknown_class_handler function if the class is not
458 found. */
459 objc_EXPORT Class objc_lookUpClass (const char *name);
460
461 /* Return the meta class associated to the class with name 'name', if
462 it is already registered with the runtime. First, it finds the
463 class using objc_getClass(). Then, it returns the associated meta
464 class. If the class could not be found using objc_getClass(),
465 returns Nil. */
466 objc_EXPORT Class objc_getMetaClass (const char *name);
467
468 /* This is identical to objc_getClass(), but if the class is not found,
469 it aborts the process instead of returning Nil. */
470 objc_EXPORT Class objc_getRequiredClass (const char *name);
471
472 /* If 'returnValue' is NULL, 'objc_getClassList' returns the number of
473 classes currently registered with the runtime. If 'returnValue' is
474 not NULL, it should be a (Class *) pointer to an area of memory
475 which can contain up to 'maxNumberOfClassesToReturn' Class records.
476 'objc_getClassList' will fill the area pointed to by 'returnValue'
477 with all the Classes registered with the runtime (or up to
478 maxNumberOfClassesToReturn if there are more than
479 maxNumberOfClassesToReturn). The function return value is the
480 number of classes actually returned in 'returnValue'. */
481 objc_EXPORT int objc_getClassList (Class *returnValue, int maxNumberOfClassesToReturn);
482
483 /* Compatibility Note: The Apple/NeXT runtime also has
484
485 Class objc_getFutureClass (const char *name);
486 void objc_setFutureClass (Class class_, const char *name);
487
488 the documentation is unclear on what they are supposed to do, and
489 the GNU Objective-C Runtime currently does not provide them. */
490
491 /* Return the name of the class 'class_', or the string "nil" if the
492 class_ is Nil. */
493 objc_EXPORT const char * class_getName (Class class_);
494
495 /* Return YES if 'class_' is a meta class, and NO if not. If 'class_'
496 is Nil, return NO. */
497 objc_EXPORT BOOL class_isMetaClass (Class class_);
498
499 /* Return the superclass of 'class_'. If 'class_' is Nil, or it is a
500 root class, return Nil. This function also works if 'class_' is a
501 class being constructed, that is, a class returned by
502 objc_allocateClassPair() but before it has been registered with the
503 runtime using objc_registerClassPair(). */
504 objc_EXPORT Class class_getSuperclass (Class class_);
505
506 /* Return the 'version' number of the class, which is an integer that
507 can be used to track changes in the class API, methods and
508 variables. If class_ is Nil, return 0. If class_ is not Nil, the
509 version is 0 unless class_setVersion() has been called to set a
510 different one.
511
512 Please note that internally the version is a long, but the API only
513 allows you to set and retrieve int values. */
514 objc_EXPORT int class_getVersion (Class class_);
515
516 /* Set the 'version' number of the class, which is an integer that can
517 be used to track changes in the class API, methods and variables.
518 If 'class_' is Nil, does nothing.
519
520 This is typically used internally by "Foundation" libraries such as
521 GNUstep Base to support serialization / deserialization of objects
522 that work across changes in the classes. If you are using such a
523 library, you probably want to use their versioning API, which may
524 be based on this one, but is integrated with the rest of the
525 library.
526
527 Please note that internally the version is a long, but the API only
528 allows you to set and retrieve int values. */
529 objc_EXPORT void class_setVersion (Class class_, int version);
530
531 /* Return the size in bytes (a byte is the size of a char) of an
532 instance of the class. If class_ is Nil, return 0; else it return
533 a non-zero number (since the 'isa' instance variable is required
534 for all classes). */
535 objc_EXPORT size_t class_getInstanceSize (Class class_);
536
537 /* Change the implementation of the method. It also searches all
538 classes for any class implementing the method, and replaces the
539 existing implementation with the new one. For that to work,
540 'method' must be a method returned by class_getInstanceMethod() or
541 class_getClassMethod() as the matching is done by comparing the
542 pointers; in that case, only the implementation in the class is
543 modified. Return the previous implementation that has been
544 replaced. If method or implementation is NULL, do nothing and
545 return NULL. */
546 objc_EXPORT IMP
547 method_setImplementation (Method method, IMP implementation);
548
549 /* Swap the implementation of two methods in a single, atomic
550 operation. This is equivalent to getting the implementation of
551 each method and then calling method_setImplementation() on the
552 other one. For this to work, the two methods must have been
553 returned by class_getInstanceMethod() or class_getClassMethod().
554 If 'method_a' or 'method_b' is NULL, do nothing. */
555 objc_EXPORT void
556 method_exchangeImplementations (Method method_a, Method method_b);
557
558 /* Create a new class/meta-class pair. This function is called to
559 create a new class at runtime. The class is created with
560 superclass 'superclass' (use 'Nil' to create a new root class) and
561 name 'class_name'. 'extraBytes' can be used to specify some extra
562 space for indexed variables to be added at the end of the class and
563 meta-class objects (it is recommended that you set extraBytes to
564 0). Once you have created the class, it is not usable yet. You
565 need to add any instance variables (by using class_addIvar()), any
566 instance methods (by using class_addMethod()) and any class methods
567 (by using class_addMethod() on the meta-class, as in
568 class_addMethod (object_getClass (class), method)) that are
569 required, and then you need to call objc_registerClassPair() to
570 activate the class. If you need to create a hierarchy of classes,
571 you need to create and register them one at a time. You cannot
572 create a new class using another class in construction as
573 superclass. Return Nil if 'class-name' is NULL or if a class with
574 that name already exists or 'superclass' is a class still in
575 construction.
576
577 Implementation Note: in the GNU runtime, allocating a class pair
578 only creates the structures for the class pair, but does not
579 register anything with the runtime. The class is registered with
580 the runtime only when objc_registerClassPair() is called. In
581 particular, if a class is in construction, objc_getClass() will not
582 find it, the superclass will not know about it,
583 class_getSuperclass() will return Nil and another thread may
584 allocate a class pair with the same name; the conflict will only be
585 detected when the classes are registered with the runtime.
586 */
587 objc_EXPORT Class
588 objc_allocateClassPair (Class super_class, const char *class_name,
589 size_t extraBytes);
590
591 /* Register a class pair that was created with
592 objc_allocateClassPair(). After you register a class, you can no
593 longer make changes to its instance variables, but you can start
594 creating instances of it. Do nothing if 'class_' is NULL or if it
595 is not a class allocated by objc_allocateClassPair() and still in
596 construction. */
597 objc_EXPORT void
598 objc_registerClassPair (Class class_);
599
600 /* Dispose of a class pair created using objc_allocateClassPair().
601 Call this function if you started creating a new class with
602 objc_allocateClassPair() but then want to abort the process. You
603 should not access 'class_' after calling this method. Note that if
604 'class_' has already been registered with the runtime via
605 objc_registerClassPair(), this function does nothing; you can only
606 dispose of class pairs that are still being constructed. Do
607 nothing if class is 'Nil' or if 'class_' is not a class being
608 constructed. */
609 objc_EXPORT void
610 objc_disposeClassPair (Class class_);
611
612 /* Compatibility Note: The Apple/NeXT runtime has the function
613 objc_duplicateClass () but it's undocumented. The GNU runtime does
614 not have it. */
615
616
617 /** Implementation: the following functions are in sendmsg.c. */
618
619 /* Return the instance method with selector 'selector' of class
620 'class_', or NULL if the class (or one of its superclasses) does
621 not implement the method. Return NULL if class_ is Nil or selector
622 is NULL. Calling this function may trigger a call to
623 +resolveInstanceMethod:, but does not return a forwarding
624 function. */
625 objc_EXPORT Method class_getInstanceMethod (Class class_, SEL selector);
626
627 /* Return the class method with selector 'selector' of class 'class_',
628 or NULL if the class (or one of its superclasses) does not
629 implement the method. Return NULL if class_ is Nil or selector is
630 NULL. Calling this function may trigger a call to
631 +resolveClassMethod:, but does not return a forwarding
632 function. */
633 objc_EXPORT Method class_getClassMethod (Class class_, SEL selector);
634
635 /* Return the IMP (pointer to the function implementing a method) for
636 the instance method with selector 'selector' in class 'class_'.
637 This is the same routine that is used while messaging, and should
638 be very fast. Note that you most likely would need to cast the
639 return function pointer to a function pointer with the appropriate
640 arguments and return type before calling it. To get a class
641 method, you can pass the meta-class as the class_ argument (ie, use
642 class_getMethodImplementation (object_getClass (class_),
643 selector)). Return NULL if class_ is Nil or selector is NULL.
644 This function first looks for an existing method; if it is not
645 found, it calls +resolveClassMethod: or +resolveInstanceMethod:
646 (depending on whether a class or instance method is being looked
647 up) if it is implemented. If the method returns YES, then it tries
648 the look up again (the assumption being that +resolveClassMethod:
649 or resolveInstanceMethod: will add the method using
650 class_addMethod()). If it is still not found, it returns a
651 forwarding function. */
652 objc_EXPORT IMP class_getMethodImplementation (Class class_, SEL selector);
653
654 /* Compatibility Note: the Apple/NeXT runtime has the function
655 class_getMethodImplementation_stret () which currently does not
656 exist on the GNU runtime because the messaging implementation is
657 different. */
658
659 /* Return YES if class 'class_' has an instance method implementing
660 selector 'selector', and NO if not. Return NO if class_ is Nil or
661 selector is NULL. If you need to check a class method, use the
662 meta-class as the class_ argument (ie, use class_respondsToSelector
663 (object_getClass (class_), selector)). */
664 objc_EXPORT BOOL class_respondsToSelector (Class class_, SEL selector);
665
666 /* Add a method to a class. Use this function to add a new method to
667 a class (potentially overriding a method with the same selector in
668 the superclass); if you want to modify an existing method, use
669 method_setImplementation() instead (or class_replaceMethod ()).
670 This method adds an instance method to 'class_'; to add a class
671 method, get the meta class first, then add the method to the meta
672 class, that is, use
673
674 class_addMethod (object_getClass (class_), selector,
675 implementation, type);
676
677 Return YES if the method was added, and NO if not. Do nothing if
678 one of the arguments is NULL. */
679 objc_EXPORT BOOL class_addMethod (Class class_, SEL selector, IMP implementation,
680 const char *method_types);
681
682 /* Replace a method in a class. If the class already have a method
683 with this 'selector', find it and use method_setImplementation() to
684 replace the implementation with 'implementation' (method_types is
685 ignored in that case). If the class does not already have a method
686 with this 'selector', call 'class_addMethod() to add it.
687
688 Return the previous implementation of the method, or NULL if none
689 was found. Return NULL if any of the arguments is NULL. */
690 objc_EXPORT IMP class_replaceMethod (Class class_, SEL selector, IMP implementation,
691 const char *method_types);
692
693
694 /** Implementation: the following functions are in methods.c. */
695
696 /* Return the selector for method 'method'. Return NULL if 'method'
697 is NULL.
698
699 This function is misnamed; it should be called
700 'method_getSelector'. To get the actual name, get the selector,
701 then the name from the selector (ie, use sel_getName
702 (method_getName (method))). */
703 objc_EXPORT SEL method_getName (Method method);
704
705 /* Return the IMP of the method. Return NULL if 'method' is NULL. */
706 objc_EXPORT IMP method_getImplementation (Method method);
707
708 /* Return the type encoding of the method. Return NULL if 'method' is
709 NULL. */
710 objc_EXPORT const char * method_getTypeEncoding (Method method);
711
712 /* Return a method description for the method. Return NULL if
713 'method' is NULL. */
714 objc_EXPORT struct objc_method_description * method_getDescription (Method method);
715
716 /* Return all the instance methods of the class. The return value of
717 the function is a pointer to an area, allocated with malloc(), that
718 contains all the instance methods of the class. It does not
719 include instance methods of superclasses. The list is terminated
720 by NULL. Optionally, if you pass a non-NULL
721 'numberOfReturnedMethods' pointer, the unsigned int that it points
722 to will be filled with the number of instance methods returned. To
723 get the list of class methods, pass the meta-class in the 'class_'
724 argument, (ie, use class_copyMethodList (object_getClass (class_),
725 &numberOfReturnedMethods)). */
726 objc_EXPORT Method * class_copyMethodList (Class class_, unsigned int *numberOfReturnedMethods);
727
728
729 /** Implementation: the following functions are in encoding.c. */
730
731 /* Return the number of arguments that the method 'method' expects.
732 Note that all methods need two implicit arguments ('self' for the
733 receiver, and '_cmd' for the selector). Return 0 if 'method' is
734 NULL. */
735 objc_EXPORT unsigned int method_getNumberOfArguments (Method method);
736
737 /* Return the string encoding for the return type of method 'method'.
738 The string is a standard zero-terminated string in an area of
739 memory allocated with malloc(); you should free it with free() when
740 you finish using it. Return an empty string if method is NULL. */
741 objc_EXPORT char * method_copyReturnType (Method method);
742
743 /* Return the string encoding for the argument type of method
744 'method', argument number 'argumentNumber' ('argumentNumber' is 0
745 for self, 1 for _cmd, and 2 or more for the additional arguments if
746 any). The string is a standard zero-terminated string in an area
747 of memory allocated with malloc(); you should free it with free()
748 when you finish using it. Return an empty string if method is NULL
749 or if 'argumentNumber' refers to a non-existing argument. */
750 objc_EXPORT char * method_copyArgumentType (Method method, unsigned int argumentNumber);
751
752 /* Return the string encoding for the return type of method 'method'.
753 The string is returned by copying it into the supplied
754 'returnValue' string, which is of size 'returnValueSize'. No more
755 than 'returnValueSize' characters are copied; if the encoding is
756 smaller than 'returnValueSize', the rest of 'returnValue' is filled
757 with zeros. If it is bigger, it is truncated (and would not be
758 zero-terminated). You should supply a big enough
759 'returnValueSize'. If the method is NULL, returnValue is set to a
760 string of zeros. */
761 objc_EXPORT void method_getReturnType (Method method, char *returnValue,
762 size_t returnValueSize);
763
764 /* Return the string encoding for the argument type of method
765 'method', argument number 'argumentNumber' ('argumentNumber' is 0
766 for self, 1 for _cmd, and 2 or more for the additional arguments if
767 any). The string is returned by copying it into the supplied
768 'returnValue' string, which is of size 'returnValueSize'. No more
769 than 'returnValueSize' characters are copied; if the encoding is
770 smaller than 'returnValueSize', the rest of 'returnValue' is filled
771 with zeros. If it is bigger, it is truncated (and would not be
772 zero-terminated). You should supply a big enough
773 'returnValueSize'. If the method is NULL, returnValue is set to a
774 string of zeros. */
775 objc_EXPORT void method_getArgumentType (Method method, unsigned int argumentNumber,
776 char *returnValue, size_t returnValueSize);
777
778
779 /** Implementation: the following functions are in protocols.c. */
780
781 /* Return the protocol with name 'name', or nil if it the protocol is
782 not known to the runtime. */
783 objc_EXPORT Protocol *objc_getProtocol (const char *name);
784
785 /* Return all the protocols known to the runtime. The return value of
786 the function is a pointer to an area, allocated with malloc(), that
787 contains all the protocols known to the runtime; the list is
788 terminated by NULL. You should free this area using free() once
789 you no longer need it. Optionally, if you pass a non-NULL
790 'numberOfReturnedProtocols' pointer, the unsigned int that it
791 points to will be filled with the number of protocols returned. If
792 there are no protocols known to the runtime, NULL is returned. */
793 objc_EXPORT Protocol **objc_copyProtocolList (unsigned int *numberOfReturnedProtocols);
794
795 /* Add a protocol to a class, and return YES if it was done
796 successfully, and NO if not. At the moment, NO should only happen
797 if class_ or protocol are nil, if the protocol is not a Protocol
798 object or if the class already conforms to the protocol. */
799 objc_EXPORT BOOL class_addProtocol (Class class_, Protocol *protocol);
800
801 /* Return YES if the class 'class_' conforms to Protocol 'protocol',
802 and NO if not. This function does not check superclasses; if you
803 want to check for superclasses (in the way that [NSObject
804 +conformsToProtocol:] does) you need to iterate over the class
805 hierarchy using class_getSuperclass(), and call
806 class_conformsToProtocol() for each of them. */
807 objc_EXPORT BOOL class_conformsToProtocol (Class class_, Protocol *protocol);
808
809 /* Return all the protocols that the class conforms to. The return
810 value of the function is a pointer to an area, allocated with
811 malloc(), that contains all the protocols formally adopted by the
812 class. It does not include protocols adopted by superclasses. The
813 list is terminated by NULL. Optionally, if you pass a non-NULL
814 'numberOfReturnedProtocols' pointer, the unsigned int that it
815 points to will be filled with the number of protocols returned.
816 This function does not return protocols that superclasses conform
817 to. */
818 objc_EXPORT Protocol **class_copyProtocolList (Class class_, unsigned int *numberOfReturnedProtocols);
819
820 /* Return YES if protocol 'protocol' conforms to protocol
821 'anotherProtocol', and NO if not. Note that if one of the two
822 protocols is nil, it returns NO. */
823 objc_EXPORT BOOL protocol_conformsToProtocol (Protocol *protocol, Protocol *anotherProtocol);
824
825 /* Return YES if protocol 'protocol' is the same as protocol
826 'anotherProtocol', and 'NO' if not. Note that it returns YES if
827 the two protocols are both nil. */
828 objc_EXPORT BOOL protocol_isEqual (Protocol *protocol, Protocol *anotherProtocol);
829
830 /* Return the name of protocol 'protocol'. If 'protocol' is nil or is
831 not a Protocol, return NULL. */
832 objc_EXPORT const char *protocol_getName (Protocol *protocol);
833
834 /* Return the method description for the method with selector
835 'selector' in protocol 'protocol'; if 'requiredMethod' is YES, the
836 function searches the list of required methods; if NO, the list of
837 optional methods. If 'instanceMethod' is YES, the function search
838 for an instance method; if NO, for a class method. If there is no
839 matching method, an objc_method_description structure with both
840 name and types set to NULL is returned. This function will only
841 find methods that are directly declared in the protocol itself, not
842 in other protocols that this protocol adopts.
843
844 Note that the traditional ABI does not store the list of optional
845 methods of a protocol in a compiled module, so the traditional ABI
846 will always return (NULL, NULL) when requiredMethod == NO. */
847 objc_EXPORT struct objc_method_description protocol_getMethodDescription (Protocol *protocol,
848 SEL selector,
849 BOOL requiredMethod,
850 BOOL instanceMethod);
851
852 /* Return the method descriptions of all the methods of the protocol.
853 The return value of the function is a pointer to an area, allocated
854 with malloc(), that contains all the method descriptions of the
855 methods of the protocol. It does not recursively include methods
856 of the protocols adopted by this protocol. The list is terminated
857 by a NULL objc_method_description (one with both fields set to
858 NULL). Optionally, if you pass a non-NULL
859 'numberOfReturnedMethods' pointer, the unsigned int that it points
860 to will be filled with the number of properties returned.
861
862 Note that the traditional ABI does not store the list of optional
863 methods of a protocol in a compiled module, so the traditional ABI
864 will always return an empty list if requiredMethod is set to
865 NO. */
866 objc_EXPORT struct objc_method_description *protocol_copyMethodDescriptionList (Protocol *protocol,
867 BOOL requiredMethod,
868 BOOL instanceMethod,
869 unsigned int *numberOfReturnedMethods);
870
871 /* Return the property with name 'propertyName' of the protocol
872 'protocol'. If 'requiredProperty' is YES, the function searches
873 the list of required properties; if NO, the list of optional
874 properties. If 'instanceProperty' is YES, the function searches
875 the list of instance properties; if NO, the list of class
876 properties. At the moment, optional properties and class
877 properties are not part of the Objective-C language, so both
878 'requiredProperty' and 'instanceProperty' should be set to YES.
879 This function returns NULL if the required property cannot be
880 found.
881
882 Note that the traditional ABI does not store the list of properties
883 of a protocol in a compiled module, so the traditional ABI will
884 always return NULL. */
885 objc_EXPORT Property protocol_getProperty (Protocol *protocol, const char *propertyName,
886 BOOL requiredProperty, BOOL instanceProperty);
887
888 /* Return all the properties of the protocol. The return value of the
889 function is a pointer to an area, allocated with malloc(), that
890 contains all the properties of the protocol. It does not
891 recursively include properties of the protocols adopted by this
892 protocol. The list is terminated by NULL. Optionally, if you pass
893 a non-NULL 'numberOfReturnedProperties' pointer, the unsigned int
894 that it points to will be filled with the number of properties
895 returned.
896
897 Note that the traditional ABI does not store the list of properties
898 of a protocol in a compiled module, so the traditional ABI will
899 always return NULL and store 0 in numberOfReturnedProperties. */
900 objc_EXPORT Property *protocol_copyPropertyList (Protocol *protocol, unsigned int *numberOfReturnedProperties);
901
902 /* Return all the protocols that the protocol conforms to. The return
903 value of the function is a pointer to an area, allocated with
904 malloc(), that contains all the protocols formally adopted by the
905 protocol. It does not recursively include protocols adopted by the
906 protocols adopted by this protocol. The list is terminated by
907 NULL. Optionally, if you pass a non-NULL
908 'numberOfReturnedProtocols' pointer, the unsigned int that it
909 points to will be filled with the number of protocols returned. */
910 objc_EXPORT Protocol **protocol_copyProtocolList (Protocol *protocol, unsigned int *numberOfReturnedProtocols);
911
912
913 /** Implementation: the following hook is in init.c. */
914
915 /* This is a hook which is called by __objc_exec_class every time a
916 class or a category is loaded into the runtime. This may e.g. help
917 a dynamic loader determine the classes that have been loaded when
918 an object file is dynamically linked in. */
919 objc_EXPORT void (*_objc_load_callback)(Class _class, struct objc_category *category);
920
921
922 /** Implementation: the following functions are in objc-foreach.c. */
923
924 /* 'objc_enumerationMutation()' is called when a collection is
925 mutated while being "fast enumerated". That is a hard error, and
926 objc_enumerationMutation is called to deal with it. 'collection'
927 is the collection object that was mutated during an enumeration.
928
929 objc_enumerationMutation() will invoke the mutation handler if any
930 is set. Then, it will abort the program.
931
932 Compatibility note: the Apple runtime will not abort the program
933 after calling the mutation handler. */
934 objc_EXPORT void objc_enumerationMutation (id collection);
935
936 /* 'objc_set_enumeration_mutation_handler' can be used to set a
937 function that will be called (instead of aborting) when a fast
938 enumeration is mutated during enumeration. The handler will be
939 called with the 'collection' being mutated as the only argument and
940 it should not return; it should either exit the program, or could
941 throw an exception. The recommended implementation is to throw an
942 exception - the user can then use exception handlers to deal with
943 it.
944
945 This function is not thread safe (other threads may be trying to
946 invoke the enumeration mutation handler while you are changing it!)
947 and should be called during during the program initialization
948 before threads are started. It is mostly reserved for "Foundation"
949 libraries; in the case of GNUstep, GNUstep Base may be using this
950 function to improve the standard enumeration mutation handling.
951 You probably shouldn't use this function unless you are writing
952 your own Foundation library. */
953 objc_EXPORT void objc_setEnumerationMutationHandler (void (*handler)(id));
954
955 /* This structure (used during fast enumeration) is automatically
956 defined by the compiler (it is as if this definition was always
957 included in all Objective-C files). Note that it is usually
958 defined again with the name of NSFastEnumeration by "Foundation"
959 libraries such as GNUstep Base. And if NSFastEnumeration is
960 defined, the compiler will use it instead of
961 __objcFastEnumerationState when doing fast enumeration. */
962 /*
963 struct __objcFastEnumerationState
964 {
965 unsigned long state;
966 id *itemsPtr;
967 unsigned long *mutationsPtr;
968 unsigned long extra[5];
969 };
970 */
971
972
973 /* Compatibility Note: The Apple/NeXT runtime has the functions
974 objc_copyImageNames (), class_getImageName () and
975 objc_copyClassNamesForImage () but they are undocumented. The GNU
976 runtime does not have them at the moment. */
977
978 /* Compatibility Note: The Apple/NeXT runtime has the functions
979 objc_setAssociatedObject (), objc_getAssociatedObject (),
980 objc_removeAssociatedObjects () and the objc_AssociationPolicy type
981 and related enum. The GNU runtime does not have them yet.
982 TODO: Implement them. */
983
984 /* Compatibility Note: The Apple/NeXT runtime has the function
985 objc_setForwardHandler (). The GNU runtime does not have it
986 because messaging (and, in particular, forwarding) works in a
987 different (incompatible) way with the GNU runtime. If you need to
988 customize message forwarding at the Objective-C runtime level (that
989 is, if you are implementing your own "Foundation" library such as
990 GNUstep Base on top of the Objective-C runtime), in objc/message.h
991 there are hooks (that work in the framework of the GNU runtime) to
992 do so. */
993
994
995 /** Implementation: the following functions are in memory.c. */
996
997 /* Traditional GNU Objective-C Runtime functions that are used for
998 memory allocation and disposal. These functions are used in the
999 same way as you use malloc, realloc, calloc and free and make sure
1000 that memory allocation works properly with the garbage
1001 collector.
1002
1003 Compatibility Note: these functions are not available with the
1004 Apple/NeXT runtime. */
1005
1006 objc_EXPORT void *objc_malloc(size_t size);
1007
1008 /* FIXME: Shouldn't the following be called objc_malloc_atomic ? The
1009 GC function is GC_malloc_atomic() which makes sense.
1010 */
1011 objc_EXPORT void *objc_atomic_malloc(size_t size);
1012
1013 objc_EXPORT void *objc_realloc(void *mem, size_t size);
1014
1015 objc_EXPORT void *objc_calloc(size_t nelem, size_t size);
1016
1017 objc_EXPORT void objc_free(void *mem);
1018
1019
1020 /** Implementation: the following functions are in gc.c. */
1021
1022 /* The GNU Objective-C Runtime has a different implementation of
1023 garbage collection.
1024
1025 Compatibility Note: these functions are not available with the
1026 Apple/NeXT runtime. */
1027
1028 /* Mark the instance variable as inaccessible to the garbage
1029 collector. */
1030 objc_EXPORT void class_ivar_set_gcinvisible (Class _class,
1031 const char* ivarname,
1032 BOOL gcInvisible);
1033
1034
1035 /** Implementation: the following functions are in encoding.c. */
1036
1037 /* Traditional GNU Objective-C Runtime functions that are currently
1038 used to implement method forwarding.
1039
1040 Compatibility Note: these functions are not available with the
1041 Apple/NeXT runtime. */
1042
1043 /* Return the size of a variable which has the specified 'type'
1044 encoding. */
1045 objc_EXPORT int objc_sizeof_type (const char *type);
1046
1047 /* Return the align of a variable which has the specified 'type'
1048 encoding. */
1049 objc_EXPORT int objc_alignof_type (const char *type);
1050
1051 /* Return the aligned size of a variable which has the specified
1052 'type' encoding. The aligned size is the size rounded up to the
1053 nearest alignment. */
1054 objc_EXPORT int objc_aligned_size (const char *type);
1055
1056 /* Return the promoted size of a variable which has the specified
1057 'type' encoding. This is the size rounded up to the nearest
1058 integral of the wordsize, taken to be the size of a void *. */
1059 objc_EXPORT int objc_promoted_size (const char *type);
1060
1061
1062 /* The following functions are used when parsing the type encoding of
1063 methods, to skip over parts that are ignored. They take as
1064 argument a pointer to a location inside the type encoding of a
1065 method (which is a string) and return a new pointer, pointing to a
1066 new location inside the string after having skipped the unwanted
1067 information. */
1068
1069 /* Skip some type qualifiers (_C_CONST, _C_IN, etc). These may
1070 eventually precede typespecs occurring in method prototype
1071 encodings. */
1072 objc_EXPORT const char *objc_skip_type_qualifiers (const char *type);
1073
1074 /* Skip one typespec element (_C_CLASS, _C_SEL, etc). If the typespec
1075 is prepended by type qualifiers, these are skipped as well. */
1076 objc_EXPORT const char *objc_skip_typespec (const char *type);
1077
1078 /* Skip an offset. */
1079 objc_EXPORT const char *objc_skip_offset (const char *type);
1080
1081 /* Skip an argument specification (ie, skipping a typespec, which may
1082 include qualifiers, and an offset too). */
1083 objc_EXPORT const char *objc_skip_argspec (const char *type);
1084
1085 /* Read type qualifiers (_C_CONST, _C_IN, etc) from string 'type'
1086 (stopping at the first non-type qualifier found) and return an
1087 unsigned int which is the logical OR of all the corresponding flags
1088 (_F_CONST, _F_IN etc). */
1089 objc_EXPORT unsigned objc_get_type_qualifiers (const char *type);
1090
1091
1092 /* Note that the following functions work for very simple structures,
1093 but get easily confused by more complicated ones (for example,
1094 containing vectors). A better solution is required. These
1095 functions are likely to change in the next GCC release. */
1096
1097 /* The following three functions can be used to determine how a
1098 structure is laid out by the compiler. For example:
1099
1100 struct objc_struct_layout layout;
1101 int i;
1102
1103 objc_layout_structure (type, &layout);
1104 while (objc_layout_structure_next_member (&layout))
1105 {
1106 int position, align;
1107 const char *type;
1108
1109 objc_layout_structure_get_info (&layout, &position, &align, &type);
1110 printf ("element %d has offset %d, alignment %d\n",
1111 i++, position, align);
1112 }
1113
1114 These functions are used by objc_sizeof_type and objc_alignof_type
1115 functions to compute the size and alignment of structures. The
1116 previous method of computing the size and alignment of a structure
1117 was not working on some architectures, particularly on AIX, and in
1118 the presence of bitfields inside the structure. */
1119 struct objc_struct_layout
1120 {
1121 const char *original_type;
1122 const char *type;
1123 const char *prev_type;
1124 unsigned int record_size;
1125 unsigned int record_align;
1126 };
1127
1128 objc_EXPORT void objc_layout_structure (const char *type,
1129 struct objc_struct_layout *layout);
1130 objc_EXPORT BOOL objc_layout_structure_next_member (struct objc_struct_layout *layout);
1131 objc_EXPORT void objc_layout_finish_structure (struct objc_struct_layout *layout,
1132 unsigned int *size,
1133 unsigned int *align);
1134 objc_EXPORT void objc_layout_structure_get_info (struct objc_struct_layout *layout,
1135 unsigned int *offset,
1136 unsigned int *align,
1137 const char **type);
1138
1139 #ifdef __cplusplus
1140 }
1141 #endif /* __cplusplus */
1142
1143 #endif