runtime/runtime.h

   1 /*
   2  * Copyright (c) 1999-2007 Apple Inc.  All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _OBJC_RUNTIME_H
  25 #define _OBJC_RUNTIME_H
  26
  27 #include <objc/objc.h>
  28 #include <stdarg.h>
  29 #include <stdint.h>
  30 #include <stddef.h>
  31 #include <Availability.h>
  32 #include <TargetConditionals.h>
  33
  34 #if TARGET_OS_MAC
  35 #include <sys/types.h>
  36 #endif
  37
  38
  39 /* Types */
  40
  41 #if !OBJC_TYPES_DEFINED
  42
  43 /// An opaque type that represents a method in a class definition.
  44 typedef struct objc_method *Method;
  45
  46 /// An opaque type that represents an instance variable.
  47 typedef struct objc_ivar *Ivar;
  48
  49 /// An opaque type that represents a category.
  50 typedef struct objc_category *Category;
  51
  52 /// An opaque type that represents an Objective-C declared property.
  53 typedef struct objc_property *objc_property_t;
  54
  55 struct objc_class {
  56     Class _Nonnull isa  OBJC_ISA_AVAILABILITY;
  57
  58 #if !__OBJC2__
  59     Class _Nullable super_class                              OBJC2_UNAVAILABLE;
  60     const char * _Nonnull name                               OBJC2_UNAVAILABLE;
  61     long version                                             OBJC2_UNAVAILABLE;
  62     long info                                                OBJC2_UNAVAILABLE;
  63     long instance_size                                       OBJC2_UNAVAILABLE;
  64     struct objc_ivar_list * _Nullable ivars                  OBJC2_UNAVAILABLE;
  65     struct objc_method_list * _Nullable * _Nullable methodLists                    OBJC2_UNAVAILABLE;
  66     struct objc_cache * _Nonnull cache                       OBJC2_UNAVAILABLE;
  67     struct objc_protocol_list * _Nullable protocols          OBJC2_UNAVAILABLE;
  68 #endif
  69
  70 } OBJC2_UNAVAILABLE;
  71 /* Use `Class` instead of `struct objc_class *` */
  72
  73 #endif
  74
  75 #ifdef __OBJC__
  76 @class Protocol;
  77 #else
  78 typedef struct objc_object Protocol;
  79 #endif
  80
  81 /// Defines a method
  82 struct objc_method_description {
  83     SEL _Nullable name;               /**< The name of the method */
  84     char * _Nullable types;           /**< The types of the method arguments */
  85 };
  86
  87 /// Defines a property attribute
  88 typedef struct {
  89     const char * _Nonnull name;           /**< The name of the attribute */
  90     const char * _Nonnull value;          /**< The value of the attribute (usually empty) */
  91 } objc_property_attribute_t;
  92
  93
  94 /* Functions */
  95
  96 /* Working with Instances */
  97
  98 /**
  99  * Returns a copy of a given object.
 100  *
 101  * @param obj An Objective-C object.
 102  * @param size The size of the object \e obj.
 103  *
 104  * @return A copy of \e obj.
 105  */
 106 OBJC_EXPORT id _Nullable object_copy(id _Nullable obj, size_t size)
 107     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 108     OBJC_ARC_UNAVAILABLE;
 109
 110 /**
 111  * Frees the memory occupied by a given object.
 112  *
 113  * @param obj An Objective-C object.
 114  *
 115  * @return nil
 116  */
 117 OBJC_EXPORT id _Nullable
 118 object_dispose(id _Nullable obj)
 119     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 120     OBJC_ARC_UNAVAILABLE;
 121
 122 /**
 123  * Returns the class of an object.
 124  *
 125  * @param obj The object you want to inspect.
 126  *
 127  * @return The class object of which \e object is an instance,
 128  *  or \c Nil if \e object is \c nil.
 129  */
 130 OBJC_EXPORT Class _Nullable
 131 object_getClass(id _Nullable obj)
 132     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 133
 134 /**
 135  * Sets the class of an object.
 136  *
 137  * @param obj The object to modify.
 138  * @param cls A class object.
 139  *
 140  * @return The previous value of \e object's class, or \c Nil if \e object is \c nil.
 141  */
 142 OBJC_EXPORT Class _Nullable
 143 object_setClass(id _Nullable obj, Class _Nonnull cls)
 144     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 145
 146
 147 /**
 148  * Returns whether an object is a class object.
 149  *
 150  * @param obj An Objective-C object.
 151  *
 152  * @return true if the object is a class or metaclass, false otherwise.
 153  */
 154 OBJC_EXPORT BOOL
 155 object_isClass(id _Nullable obj)
 156     OBJC_AVAILABLE(10.10, 8.0, 9.0, 1.0, 2.0);
 157
 158
 159 /**
 160  * Reads the value of an instance variable in an object.
 161  *
 162  * @param obj The object containing the instance variable whose value you want to read.
 163  * @param ivar The Ivar describing the instance variable whose value you want to read.
 164  *
 165  * @return The value of the instance variable specified by \e ivar, or \c nil if \e object is \c nil.
 166  *
 167  * @note \c object_getIvar is faster than \c object_getInstanceVariable if the Ivar
 168  *  for the instance variable is already known.
 169  */
 170 OBJC_EXPORT id _Nullable
 171 object_getIvar(id _Nullable obj, Ivar _Nonnull ivar)
 172     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 173
 174 /**
 175  * Sets the value of an instance variable in an object.
 176  *
 177  * @param obj The object containing the instance variable whose value you want to set.
 178  * @param ivar The Ivar describing the instance variable whose value you want to set.
 179  * @param value The new value for the instance variable.
 180  *
 181  * @note Instance variables with known memory management (such as ARC strong and weak)
 182  *  use that memory management. Instance variables with unknown memory management
 183  *  are assigned as if they were unsafe_unretained.
 184  * @note \c object_setIvar is faster than \c object_setInstanceVariable if the Ivar
 185  *  for the instance variable is already known.
 186  */
 187 OBJC_EXPORT void
 188 object_setIvar(id _Nullable obj, Ivar _Nonnull ivar, id _Nullable value)
 189     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 190
 191 /**
 192  * Sets the value of an instance variable in an object.
 193  *
 194  * @param obj The object containing the instance variable whose value you want to set.
 195  * @param ivar The Ivar describing the instance variable whose value you want to set.
 196  * @param value The new value for the instance variable.
 197  *
 198  * @note Instance variables with known memory management (such as ARC strong and weak)
 199  *  use that memory management. Instance variables with unknown memory management
 200  *  are assigned as if they were strong.
 201  * @note \c object_setIvar is faster than \c object_setInstanceVariable if the Ivar
 202  *  for the instance variable is already known.
 203  */
 204 OBJC_EXPORT void
 205 object_setIvarWithStrongDefault(id _Nullable obj, Ivar _Nonnull ivar,
 206                                 id _Nullable value)
 207     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 208
 209 /**
 210  * Changes the value of an instance variable of a class instance.
 211  *
 212  * @param obj A pointer to an instance of a class. Pass the object containing
 213  *  the instance variable whose value you wish to modify.
 214  * @param name A C string. Pass the name of the instance variable whose value you wish to modify.
 215  * @param value The new value for the instance variable.
 216  *
 217  * @return A pointer to the \c Ivar data structure that defines the type and
 218  *  name of the instance variable specified by \e name.
 219  *
 220  * @note Instance variables with known memory management (such as ARC strong and weak)
 221  *  use that memory management. Instance variables with unknown memory management
 222  *  are assigned as if they were unsafe_unretained.
 223  */
 224 OBJC_EXPORT Ivar _Nullable
 225 object_setInstanceVariable(id _Nullable obj, const char * _Nonnull name,
 226                            void * _Nullable value)
 227     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 228     OBJC_ARC_UNAVAILABLE;
 229
 230 /**
 231  * Changes the value of an instance variable of a class instance.
 232  *
 233  * @param obj A pointer to an instance of a class. Pass the object containing
 234  *  the instance variable whose value you wish to modify.
 235  * @param name A C string. Pass the name of the instance variable whose value you wish to modify.
 236  * @param value The new value for the instance variable.
 237  *
 238  * @return A pointer to the \c Ivar data structure that defines the type and
 239  *  name of the instance variable specified by \e name.
 240  *
 241  * @note Instance variables with known memory management (such as ARC strong and weak)
 242  *  use that memory management. Instance variables with unknown memory management
 243  *  are assigned as if they were strong.
 244  */
 245 OBJC_EXPORT Ivar _Nullable
 246 object_setInstanceVariableWithStrongDefault(id _Nullable obj,
 247                                             const char * _Nonnull name,
 248                                             void * _Nullable value)
 249     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0)
 250     OBJC_ARC_UNAVAILABLE;
 251
 252 /**
 253  * Obtains the value of an instance variable of a class instance.
 254  *
 255  * @param obj A pointer to an instance of a class. Pass the object containing
 256  *  the instance variable whose value you wish to obtain.
 257  * @param name A C string. Pass the name of the instance variable whose value you wish to obtain.
 258  * @param outValue On return, contains a pointer to the value of the instance variable.
 259  *
 260  * @return A pointer to the \c Ivar data structure that defines the type and name of
 261  *  the instance variable specified by \e name.
 262  */
 263 OBJC_EXPORT Ivar _Nullable
 264 object_getInstanceVariable(id _Nullable obj, const char * _Nonnull name,
 265                            void * _Nullable * _Nullable outValue)
 266     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 267     OBJC_ARC_UNAVAILABLE;
 268
 269
 270 /* Obtaining Class Definitions */
 271
 272 /**
 273  * Returns the class definition of a specified class.
 274  *
 275  * @param name The name of the class to look up.
 276  *
 277  * @return The Class object for the named class, or \c nil
 278  *  if the class is not registered with the Objective-C runtime.
 279  *
 280  * @note \c objc_getClass is different from \c objc_lookUpClass in that if the class
 281  *  is not registered, \c objc_getClass calls the class handler callback and then checks
 282  *  a second time to see whether the class is registered. \c objc_lookUpClass does
 283  *  not call the class handler callback.
 284  *
 285  * @warning Earlier implementations of this function (prior to OS X v10.0)
 286  *  terminate the program if the class does not exist.
 287  */
 288 OBJC_EXPORT Class _Nullable
 289 objc_getClass(const char * _Nonnull name)
 290     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 291
 292 /**
 293  * Returns the metaclass definition of a specified class.
 294  *
 295  * @param name The name of the class to look up.
 296  *
 297  * @return The \c Class object for the metaclass of the named class, or \c nil if the class
 298  *  is not registered with the Objective-C runtime.
 299  *
 300  * @note If the definition for the named class is not registered, this function calls the class handler
 301  *  callback and then checks a second time to see if the class is registered. However, every class
 302  *  definition must have a valid metaclass definition, and so the metaclass definition is always returned,
 303  *  whether it’s valid or not.
 304  */
 305 OBJC_EXPORT Class _Nullable
 306 objc_getMetaClass(const char * _Nonnull name)
 307     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 308
 309 /**
 310  * Returns the class definition of a specified class.
 311  *
 312  * @param name The name of the class to look up.
 313  *
 314  * @return The Class object for the named class, or \c nil if the class
 315  *  is not registered with the Objective-C runtime.
 316  *
 317  * @note \c objc_getClass is different from this function in that if the class is not
 318  *  registered, \c objc_getClass calls the class handler callback and then checks a second
 319  *  time to see whether the class is registered. This function does not call the class handler callback.
 320  */
 321 OBJC_EXPORT Class _Nullable
 322 objc_lookUpClass(const char * _Nonnull name)
 323     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 324
 325 /**
 326  * Returns the class definition of a specified class.
 327  *
 328  * @param name The name of the class to look up.
 329  *
 330  * @return The Class object for the named class.
 331  *
 332  * @note This function is the same as \c objc_getClass, but kills the process if the class is not found.
 333  * @note This function is used by ZeroLink, where failing to find a class would be a compile-time link error without ZeroLink.
 334  */
 335 OBJC_EXPORT Class _Nonnull
 336 objc_getRequiredClass(const char * _Nonnull name)
 337     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 338
 339 /**
 340  * Obtains the list of registered class definitions.
 341  *
 342  * @param buffer An array of \c Class values. On output, each \c Class value points to
 343  *  one class definition, up to either \e bufferCount or the total number of registered classes,
 344  *  whichever is less. You can pass \c NULL to obtain the total number of registered class
 345  *  definitions without actually retrieving any class definitions.
 346  * @param bufferCount An integer value. Pass the number of pointers for which you have allocated space
 347  *  in \e buffer. On return, this function fills in only this number of elements. If this number is less
 348  *  than the number of registered classes, this function returns an arbitrary subset of the registered classes.
 349  *
 350  * @return An integer value indicating the total number of registered classes.
 351  *
 352  * @note The Objective-C runtime library automatically registers all the classes defined in your source code.
 353  *  You can create class definitions at runtime and register them with the \c objc_addClass function.
 354  *
 355  * @warning You cannot assume that class objects you get from this function are classes that inherit from \c NSObject,
 356  *  so you cannot safely call any methods on such classes without detecting that the method is implemented first.
 357  */
 358 OBJC_EXPORT int
 359 objc_getClassList(Class _Nonnull * _Nullable buffer, int bufferCount)
 360     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 361
 362 /**
 363  * Creates and returns a list of pointers to all registered class definitions.
 364  *
 365  * @param outCount An integer pointer used to store the number of classes returned by
 366  *  this function in the list. It can be \c nil.
 367  *
 368  * @return A nil terminated array of classes. It must be freed with \c free().
 369  *
 370  * @see objc_getClassList
 371  */
 372 OBJC_EXPORT Class _Nonnull * _Nullable
 373 objc_copyClassList(unsigned int * _Nullable outCount)
 374     OBJC_AVAILABLE(10.7, 3.1, 9.0, 1.0, 2.0);
 375
 376
 377 /* Working with Classes */
 378
 379 /**
 380  * Returns the name of a class.
 381  *
 382  * @param cls A class object.
 383  *
 384  * @return The name of the class, or the empty string if \e cls is \c Nil.
 385  */
 386 OBJC_EXPORT const char * _Nonnull
 387 class_getName(Class _Nullable cls)
 388     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 389
 390 /**
 391  * Returns a Boolean value that indicates whether a class object is a metaclass.
 392  *
 393  * @param cls A class object.
 394  *
 395  * @return \c YES if \e cls is a metaclass, \c NO if \e cls is a non-meta class,
 396  *  \c NO if \e cls is \c Nil.
 397  */
 398 OBJC_EXPORT BOOL
 399 class_isMetaClass(Class _Nullable cls)
 400     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 401
 402 /**
 403  * Returns the superclass of a class.
 404  *
 405  * @param cls A class object.
 406  *
 407  * @return The superclass of the class, or \c Nil if
 408  *  \e cls is a root class, or \c Nil if \e cls is \c Nil.
 409  *
 410  * @note You should usually use \c NSObject's \c superclass method instead of this function.
 411  */
 412 OBJC_EXPORT Class _Nullable
 413 class_getSuperclass(Class _Nullable cls)
 414     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 415
 416 /**
 417  * Sets the superclass of a given class.
 418  *
 419  * @param cls The class whose superclass you want to set.
 420  * @param newSuper The new superclass for cls.
 421  *
 422  * @return The old superclass for cls.
 423  *
 424  * @warning You should not use this function.
 425  */
 426 OBJC_EXPORT Class _Nonnull
 427 class_setSuperclass(Class _Nonnull cls, Class _Nonnull newSuper)
 428     __OSX_DEPRECATED(10.5, 10.5, "not recommended")
 429     __IOS_DEPRECATED(2.0, 2.0, "not recommended")
 430     __TVOS_DEPRECATED(9.0, 9.0, "not recommended")
 431     __WATCHOS_DEPRECATED(1.0, 1.0, "not recommended")
 432     __BRIDGEOS_DEPRECATED(2.0, 2.0, "not recommended");
 433
 434 /**
 435  * Returns the version number of a class definition.
 436  *
 437  * @param cls A pointer to a \c Class data structure. Pass
 438  *  the class definition for which you wish to obtain the version.
 439  *
 440  * @return An integer indicating the version number of the class definition.
 441  *
 442  * @see class_setVersion
 443  */
 444 OBJC_EXPORT int
 445 class_getVersion(Class _Nullable cls)
 446     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 447
 448 /**
 449  * Sets the version number of a class definition.
 450  *
 451  * @param cls A pointer to an Class data structure.
 452  *  Pass the class definition for which you wish to set the version.
 453  * @param version An integer. Pass the new version number of the class definition.
 454  *
 455  * @note You can use the version number of the class definition to provide versioning of the
 456  *  interface that your class represents to other classes. This is especially useful for object
 457  *  serialization (that is, archiving of the object in a flattened form), where it is important to
 458  *  recognize changes to the layout of the instance variables in different class-definition versions.
 459  * @note Classes derived from the Foundation framework \c NSObject class can set the class-definition
 460  *  version number using the \c setVersion: class method, which is implemented using the \c class_setVersion function.
 461  */
 462 OBJC_EXPORT void
 463 class_setVersion(Class _Nullable cls, int version)
 464     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 465
 466 /**
 467  * Returns the size of instances of a class.
 468  *
 469  * @param cls A class object.
 470  *
 471  * @return The size in bytes of instances of the class \e cls, or \c 0 if \e cls is \c Nil.
 472  */
 473 OBJC_EXPORT size_t
 474 class_getInstanceSize(Class _Nullable cls)
 475     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 476
 477 /**
 478  * Returns the \c Ivar for a specified instance variable of a given class.
 479  *
 480  * @param cls The class whose instance variable you wish to obtain.
 481  * @param name The name of the instance variable definition to obtain.
 482  *
 483  * @return A pointer to an \c Ivar data structure containing information about
 484  *  the instance variable specified by \e name.
 485  */
 486 OBJC_EXPORT Ivar _Nullable
 487 class_getInstanceVariable(Class _Nullable cls, const char * _Nonnull name)
 488     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 489
 490 /**
 491  * Returns the Ivar for a specified class variable of a given class.
 492  *
 493  * @param cls The class definition whose class variable you wish to obtain.
 494  * @param name The name of the class variable definition to obtain.
 495  *
 496  * @return A pointer to an \c Ivar data structure containing information about the class variable specified by \e name.
 497  */
 498 OBJC_EXPORT Ivar _Nullable
 499 class_getClassVariable(Class _Nullable cls, const char * _Nonnull name)
 500     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 501
 502 /**
 503  * Describes the instance variables declared by a class.
 504  *
 505  * @param cls The class to inspect.
 506  * @param outCount On return, contains the length of the returned array.
 507  *  If outCount is NULL, the length is not returned.
 508  *
 509  * @return An array of pointers of type Ivar describing the instance variables declared by the class.
 510  *  Any instance variables declared by superclasses are not included. The array contains *outCount
 511  *  pointers followed by a NULL terminator. You must free the array with free().
 512  *
 513  *  If the class declares no instance variables, or cls is Nil, NULL is returned and *outCount is 0.
 514  */
 515 OBJC_EXPORT Ivar _Nonnull * _Nullable
 516 class_copyIvarList(Class _Nullable cls, unsigned int * _Nullable outCount)
 517     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 518
 519 /**
 520  * Returns a specified instance method for a given class.
 521  *
 522  * @param cls The class you want to inspect.
 523  * @param name The selector of the method you want to retrieve.
 524  *
 525  * @return The method that corresponds to the implementation of the selector specified by
 526  *  \e name for the class specified by \e cls, or \c NULL if the specified class or its
 527  *  superclasses do not contain an instance method with the specified selector.
 528  *
 529  * @note This function searches superclasses for implementations, whereas \c class_copyMethodList does not.
 530  */
 531 OBJC_EXPORT Method _Nullable
 532 class_getInstanceMethod(Class _Nullable cls, SEL _Nonnull name)
 533     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 534
 535 /**
 536  * Returns a pointer to the data structure describing a given class method for a given class.
 537  *
 538  * @param cls A pointer to a class definition. Pass the class that contains the method you want to retrieve.
 539  * @param name A pointer of type \c SEL. Pass the selector of the method you want to retrieve.
 540  *
 541  * @return A pointer to the \c Method data structure that corresponds to the implementation of the
 542  *  selector specified by aSelector for the class specified by aClass, or NULL if the specified
 543  *  class or its superclasses do not contain an instance method with the specified selector.
 544  *
 545  * @note Note that this function searches superclasses for implementations,
 546  *  whereas \c class_copyMethodList does not.
 547  */
 548 OBJC_EXPORT Method _Nullable
 549 class_getClassMethod(Class _Nullable cls, SEL _Nonnull name)
 550     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 551
 552 /**
 553  * Returns the function pointer that would be called if a
 554  * particular message were sent to an instance of a class.
 555  *
 556  * @param cls The class you want to inspect.
 557  * @param name A selector.
 558  *
 559  * @return The function pointer that would be called if \c [object name] were called
 560  *  with an instance of the class, or \c NULL if \e cls is \c Nil.
 561  *
 562  * @note \c class_getMethodImplementation may be faster than \c method_getImplementation(class_getInstanceMethod(cls, name)).
 563  * @note The function pointer returned may be a function internal to the runtime instead of
 564  *  an actual method implementation. For example, if instances of the class do not respond to
 565  *  the selector, the function pointer returned will be part of the runtime's message forwarding machinery.
 566  */
 567 OBJC_EXPORT IMP _Nullable
 568 class_getMethodImplementation(Class _Nullable cls, SEL _Nonnull name)
 569     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 570
 571 /**
 572  * Returns the function pointer that would be called if a particular
 573  * message were sent to an instance of a class.
 574  *
 575  * @param cls The class you want to inspect.
 576  * @param name A selector.
 577  *
 578  * @return The function pointer that would be called if \c [object name] were called
 579  *  with an instance of the class, or \c NULL if \e cls is \c Nil.
 580  */
 581 OBJC_EXPORT IMP _Nullable
 582 class_getMethodImplementation_stret(Class _Nullable cls, SEL _Nonnull name)
 583     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0)
 584     OBJC_ARM64_UNAVAILABLE;
 585
 586 /**
 587  * Returns a Boolean value that indicates whether instances of a class respond to a particular selector.
 588  *
 589  * @param cls The class you want to inspect.
 590  * @param sel A selector.
 591  *
 592  * @return \c YES if instances of the class respond to the selector, otherwise \c NO.
 593  *
 594  * @note You should usually use \c NSObject's \c respondsToSelector: or \c instancesRespondToSelector:
 595  *  methods instead of this function.
 596  */
 597 OBJC_EXPORT BOOL
 598 class_respondsToSelector(Class _Nullable cls, SEL _Nonnull sel)
 599     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 600
 601 /**
 602  * Describes the instance methods implemented by a class.
 603  *
 604  * @param cls The class you want to inspect.
 605  * @param outCount On return, contains the length of the returned array.
 606  *  If outCount is NULL, the length is not returned.
 607  *
 608  * @return An array of pointers of type Method describing the instance methods
 609  *  implemented by the class—any instance methods implemented by superclasses are not included.
 610  *  The array contains *outCount pointers followed by a NULL terminator. You must free the array with free().
 611  *
 612  *  If cls implements no instance methods, or cls is Nil, returns NULL and *outCount is 0.
 613  *
 614  * @note To get the class methods of a class, use \c class_copyMethodList(object_getClass(cls), &count).
 615  * @note To get the implementations of methods that may be implemented by superclasses,
 616  *  use \c class_getInstanceMethod or \c class_getClassMethod.
 617  */
 618 OBJC_EXPORT Method _Nonnull * _Nullable
 619 class_copyMethodList(Class _Nullable cls, unsigned int * _Nullable outCount)
 620     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 621
 622 /**
 623  * Returns a Boolean value that indicates whether a class conforms to a given protocol.
 624  *
 625  * @param cls The class you want to inspect.
 626  * @param protocol A protocol.
 627  *
 628  * @return YES if cls conforms to protocol, otherwise NO.
 629  *
 630  * @note You should usually use NSObject's conformsToProtocol: method instead of this function.
 631  */
 632 OBJC_EXPORT BOOL
 633 class_conformsToProtocol(Class _Nullable cls, Protocol * _Nullable protocol)
 634     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 635
 636 /**
 637  * Describes the protocols adopted by a class.
 638  *
 639  * @param cls The class you want to inspect.
 640  * @param outCount On return, contains the length of the returned array.
 641  *  If outCount is NULL, the length is not returned.
 642  *
 643  * @return An array of pointers of type Protocol* describing the protocols adopted
 644  *  by the class. Any protocols adopted by superclasses or other protocols are not included.
 645  *  The array contains *outCount pointers followed by a NULL terminator. You must free the array with free().
 646  *
 647  *  If cls adopts no protocols, or cls is Nil, returns NULL and *outCount is 0.
 648  */
 649 OBJC_EXPORT Protocol * __unsafe_unretained _Nonnull * _Nullable
 650 class_copyProtocolList(Class _Nullable cls, unsigned int * _Nullable outCount)
 651     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 652
 653 /**
 654  * Returns a property with a given name of a given class.
 655  *
 656  * @param cls The class you want to inspect.
 657  * @param name The name of the property you want to inspect.
 658  *
 659  * @return A pointer of type \c objc_property_t describing the property, or
 660  *  \c NULL if the class does not declare a property with that name,
 661  *  or \c NULL if \e cls is \c Nil.
 662  */
 663 OBJC_EXPORT objc_property_t _Nullable
 664 class_getProperty(Class _Nullable cls, const char * _Nonnull name)
 665     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 666
 667 /**
 668  * Describes the properties declared by a class.
 669  *
 670  * @param cls The class you want to inspect.
 671  * @param outCount On return, contains the length of the returned array.
 672  *  If \e outCount is \c NULL, the length is not returned.
 673  *
 674  * @return An array of pointers of type \c objc_property_t describing the properties
 675  *  declared by the class. Any properties declared by superclasses are not included.
 676  *  The array contains \c *outCount pointers followed by a \c NULL terminator. You must free the array with \c free().
 677  *
 678  *  If \e cls declares no properties, or \e cls is \c Nil, returns \c NULL and \c *outCount is \c 0.
 679  */
 680 OBJC_EXPORT objc_property_t _Nonnull * _Nullable
 681 class_copyPropertyList(Class _Nullable cls, unsigned int * _Nullable outCount)
 682     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 683
 684 /**
 685  * Returns a description of the \c Ivar layout for a given class.
 686  *
 687  * @param cls The class to inspect.
 688  *
 689  * @return A description of the \c Ivar layout for \e cls.
 690  */
 691 OBJC_EXPORT const uint8_t * _Nullable
 692 class_getIvarLayout(Class _Nullable cls)
 693     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 694
 695 /**
 696  * Returns a description of the layout of weak Ivars for a given class.
 697  *
 698  * @param cls The class to inspect.
 699  *
 700  * @return A description of the layout of the weak \c Ivars for \e cls.
 701  */
 702 OBJC_EXPORT const uint8_t * _Nullable
 703 class_getWeakIvarLayout(Class _Nullable cls)
 704     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 705
 706 /**
 707  * Adds a new method to a class with a given name and implementation.
 708  *
 709  * @param cls The class to which to add a method.
 710  * @param name A selector that specifies the name of the method being added.
 711  * @param imp A function which is the implementation of the new method. The function must take at least two arguments—self and _cmd.
 712  * @param types An array of characters that describe the types of the arguments to the method.
 713  *
 714  * @return YES if the method was added successfully, otherwise NO
 715  *  (for example, the class already contains a method implementation with that name).
 716  *
 717  * @note class_addMethod will add an override of a superclass's implementation,
 718  *  but will not replace an existing implementation in this class.
 719  *  To change an existing implementation, use method_setImplementation.
 720  */
 721 OBJC_EXPORT BOOL
 722 class_addMethod(Class _Nullable cls, SEL _Nonnull name, IMP _Nonnull imp,
 723                 const char * _Nullable types)
 724     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 725
 726 /**
 727  * Replaces the implementation of a method for a given class.
 728  *
 729  * @param cls The class you want to modify.
 730  * @param name A selector that identifies the method whose implementation you want to replace.
 731  * @param imp The new implementation for the method identified by name for the class identified by cls.
 732  * @param types An array of characters that describe the types of the arguments to the method.
 733  *  Since the function must take at least two arguments—self and _cmd, the second and third characters
 734  *  must be “@:” (the first character is the return type).
 735  *
 736  * @return The previous implementation of the method identified by \e name for the class identified by \e cls.
 737  *
 738  * @note This function behaves in two different ways:
 739  *  - If the method identified by \e name does not yet exist, it is added as if \c class_addMethod were called.
 740  *    The type encoding specified by \e types is used as given.
 741  *  - If the method identified by \e name does exist, its \c IMP is replaced as if \c method_setImplementation were called.
 742  *    The type encoding specified by \e types is ignored.
 743  */
 744 OBJC_EXPORT IMP _Nullable
 745 class_replaceMethod(Class _Nullable cls, SEL _Nonnull name, IMP _Nonnull imp,
 746                     const char * _Nullable types)
 747     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 748
 749 /**
 750  * Adds a new instance variable to a class.
 751  *
 752  * @return YES if the instance variable was added successfully, otherwise NO
 753  *         (for example, the class already contains an instance variable with that name).
 754  *
 755  * @note This function may only be called after objc_allocateClassPair and before objc_registerClassPair.
 756  *       Adding an instance variable to an existing class is not supported.
 757  * @note The class must not be a metaclass. Adding an instance variable to a metaclass is not supported.
 758  * @note The instance variable's minimum alignment in bytes is 1<<align. The minimum alignment of an instance
 759  *       variable depends on the ivar's type and the machine architecture.
 760  *       For variables of any pointer type, pass log2(sizeof(pointer_type)).
 761  */
 762 OBJC_EXPORT BOOL
 763 class_addIvar(Class _Nullable cls, const char * _Nonnull name, size_t size,
 764               uint8_t alignment, const char * _Nullable types)
 765     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 766
 767 /**
 768  * Adds a protocol to a class.
 769  *
 770  * @param cls The class to modify.
 771  * @param protocol The protocol to add to \e cls.
 772  *
 773  * @return \c YES if the method was added successfully, otherwise \c NO
 774  *  (for example, the class already conforms to that protocol).
 775  */
 776 OBJC_EXPORT BOOL
 777 class_addProtocol(Class _Nullable cls, Protocol * _Nonnull protocol)
 778     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 779
 780 /**
 781  * Adds a property to a class.
 782  *
 783  * @param cls The class to modify.
 784  * @param name The name of the property.
 785  * @param attributes An array of property attributes.
 786  * @param attributeCount The number of attributes in \e attributes.
 787  *
 788  * @return \c YES if the property was added successfully, otherwise \c NO
 789  *  (for example, the class already has that property).
 790  */
 791 OBJC_EXPORT BOOL
 792 class_addProperty(Class _Nullable cls, const char * _Nonnull name,
 793                   const objc_property_attribute_t * _Nullable attributes,
 794                   unsigned int attributeCount)
 795     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
 796
 797 /**
 798  * Replace a property of a class.
 799  *
 800  * @param cls The class to modify.
 801  * @param name The name of the property.
 802  * @param attributes An array of property attributes.
 803  * @param attributeCount The number of attributes in \e attributes.
 804  */
 805 OBJC_EXPORT void
 806 class_replaceProperty(Class _Nullable cls, const char * _Nonnull name,
 807                       const objc_property_attribute_t * _Nullable attributes,
 808                       unsigned int attributeCount)
 809     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
 810
 811 /**
 812  * Sets the Ivar layout for a given class.
 813  *
 814  * @param cls The class to modify.
 815  * @param layout The layout of the \c Ivars for \e cls.
 816  */
 817 OBJC_EXPORT void
 818 class_setIvarLayout(Class _Nullable cls, const uint8_t * _Nullable layout)
 819     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 820
 821 /**
 822  * Sets the layout for weak Ivars for a given class.
 823  *
 824  * @param cls The class to modify.
 825  * @param layout The layout of the weak Ivars for \e cls.
 826  */
 827 OBJC_EXPORT void
 828 class_setWeakIvarLayout(Class _Nullable cls, const uint8_t * _Nullable layout)
 829     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 830
 831 /**
 832  * Used by CoreFoundation's toll-free bridging.
 833  * Return the id of the named class.
 834  *
 835  * @return The id of the named class, or an uninitialized class
 836  *  structure that will be used for the class when and if it does
 837  *  get loaded.
 838  *
 839  * @warning Do not call this function yourself.
 840  */
 841 OBJC_EXPORT Class _Nonnull
 842 objc_getFutureClass(const char * _Nonnull name)
 843     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0)
 844     OBJC_ARC_UNAVAILABLE;
 845
 846
 847 /* Instantiating Classes */
 848
 849 /**
 850  * Creates an instance of a class, allocating memory for the class in the
 851  * default malloc memory zone.
 852  *
 853  * @param cls The class that you wish to allocate an instance of.
 854  * @param extraBytes An integer indicating the number of extra bytes to allocate.
 855  *  The additional bytes can be used to store additional instance variables beyond
 856  *  those defined in the class definition.
 857  *
 858  * @return An instance of the class \e cls.
 859  */
 860 OBJC_EXPORT id _Nullable
 861 class_createInstance(Class _Nullable cls, size_t extraBytes)
 862     OBJC_RETURNS_RETAINED
 863     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 864
 865 /**
 866  * Creates an instance of a class at the specific location provided.
 867  *
 868  * @param cls The class that you wish to allocate an instance of.
 869  * @param bytes The location at which to allocate an instance of \e cls.
 870  *  Must point to at least \c class_getInstanceSize(cls) bytes of well-aligned,
 871  *  zero-filled memory.
 872  *
 873  * @return \e bytes on success, \c nil otherwise. (For example, \e cls or \e bytes
 874  *  might be \c nil)
 875  *
 876  * @see class_createInstance
 877  */
 878 OBJC_EXPORT id _Nullable
 879 objc_constructInstance(Class _Nullable cls, void * _Nullable bytes)
 880     OBJC_AVAILABLE(10.6, 3.0, 9.0, 1.0, 2.0)
 881     OBJC_ARC_UNAVAILABLE;
 882
 883 /**
 884  * Destroys an instance of a class without freeing memory and removes any
 885  * associated references this instance might have had.
 886  *
 887  * @param obj The class instance to destroy.
 888  *
 889  * @return \e obj. Does nothing if \e obj is nil.
 890  *
 891  * @note CF and other clients do call this under GC.
 892  */
 893 OBJC_EXPORT void * _Nullable objc_destructInstance(id _Nullable obj)
 894     OBJC_AVAILABLE(10.6, 3.0, 9.0, 1.0, 2.0)
 895     OBJC_ARC_UNAVAILABLE;
 896
 897
 898 /* Adding Classes */
 899
 900 /**
 901  * Creates a new class and metaclass.
 902  *
 903  * @param superclass The class to use as the new class's superclass, or \c Nil to create a new root class.
 904  * @param name The string to use as the new class's name. The string will be copied.
 905  * @param extraBytes The number of bytes to allocate for indexed ivars at the end of
 906  *  the class and metaclass objects. This should usually be \c 0.
 907  *
 908  * @return The new class, or Nil if the class could not be created (for example, the desired name is already in use).
 909  *
 910  * @note You can get a pointer to the new metaclass by calling \c object_getClass(newClass).
 911  * @note To create a new class, start by calling \c objc_allocateClassPair.
 912  *  Then set the class's attributes with functions like \c class_addMethod and \c class_addIvar.
 913  *  When you are done building the class, call \c objc_registerClassPair. The new class is now ready for use.
 914  * @note Instance methods and instance variables should be added to the class itself.
 915  *  Class methods should be added to the metaclass.
 916  */
 917 OBJC_EXPORT Class _Nullable
 918 objc_allocateClassPair(Class _Nullable superclass, const char * _Nonnull name,
 919                        size_t extraBytes)
 920     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 921
 922 /**
 923  * Registers a class that was allocated using \c objc_allocateClassPair.
 924  *
 925  * @param cls The class you want to register.
 926  */
 927 OBJC_EXPORT void
 928 objc_registerClassPair(Class _Nonnull cls)
 929     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 930
 931 /**
 932  * Used by Foundation's Key-Value Observing.
 933  *
 934  * @warning Do not call this function yourself.
 935  */
 936 OBJC_EXPORT Class _Nonnull
 937 objc_duplicateClass(Class _Nonnull original, const char * _Nonnull name,
 938                     size_t extraBytes)
 939     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 940
 941 /**
 942  * Destroy a class and its associated metaclass.
 943  *
 944  * @param cls The class to be destroyed. It must have been allocated with
 945  *  \c objc_allocateClassPair
 946  *
 947  * @warning Do not call if instances of this class or a subclass exist.
 948  */
 949 OBJC_EXPORT void
 950 objc_disposeClassPair(Class _Nonnull cls)
 951     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 952
 953
 954 /* Working with Methods */
 955
 956 /**
 957  * Returns the name of a method.
 958  *
 959  * @param m The method to inspect.
 960  *
 961  * @return A pointer of type SEL.
 962  *
 963  * @note To get the method name as a C string, call \c sel_getName(method_getName(method)).
 964  */
 965 OBJC_EXPORT SEL _Nonnull
 966 method_getName(Method _Nonnull m)
 967     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 968
 969 /**
 970  * Returns the implementation of a method.
 971  *
 972  * @param m The method to inspect.
 973  *
 974  * @return A function pointer of type IMP.
 975  */
 976 OBJC_EXPORT IMP _Nonnull
 977 method_getImplementation(Method _Nonnull m)
 978     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 979
 980 /**
 981  * Returns a string describing a method's parameter and return types.
 982  *
 983  * @param m The method to inspect.
 984  *
 985  * @return A C string. The string may be \c NULL.
 986  */
 987 OBJC_EXPORT const char * _Nullable
 988 method_getTypeEncoding(Method _Nonnull m)
 989     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 990
 991 /**
 992  * Returns the number of arguments accepted by a method.
 993  *
 994  * @param m A pointer to a \c Method data structure. Pass the method in question.
 995  *
 996  * @return An integer containing the number of arguments accepted by the given method.
 997  */
 998 OBJC_EXPORT unsigned int
 999 method_getNumberOfArguments(Method _Nonnull m)
1000     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
1001
1002 /**
1003  * Returns a string describing a method's return type.
1004  *
1005  * @param m The method to inspect.
1006  *
1007  * @return A C string describing the return type. You must free the string with \c free().
1008  */
1009 OBJC_EXPORT char * _Nonnull
1010 method_copyReturnType(Method _Nonnull m)
1011     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1012
1013 /**
1014  * Returns a string describing a single parameter type of a method.
1015  *
1016  * @param m The method to inspect.
1017  * @param index The index of the parameter to inspect.
1018  *
1019  * @return A C string describing the type of the parameter at index \e index, or \c NULL
1020  *  if method has no parameter index \e index. You must free the string with \c free().
1021  */
1022 OBJC_EXPORT char * _Nullable
1023 method_copyArgumentType(Method _Nonnull m, unsigned int index)
1024     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1025
1026 /**
1027  * Returns by reference a string describing a method's return type.
1028  *
1029  * @param m The method you want to inquire about.
1030  * @param dst The reference string to store the description.
1031  * @param dst_len The maximum number of characters that can be stored in \e dst.
1032  *
1033  * @note The method's return type string is copied to \e dst.
1034  *  \e dst is filled as if \c strncpy(dst, parameter_type, dst_len) were called.
1035  */
1036 OBJC_EXPORT void
1037 method_getReturnType(Method _Nonnull m, char * _Nonnull dst, size_t dst_len)
1038     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1039
1040 /**
1041  * Returns by reference a string describing a single parameter type of a method.
1042  *
1043  * @param m The method you want to inquire about.
1044  * @param index The index of the parameter you want to inquire about.
1045  * @param dst The reference string to store the description.
1046  * @param dst_len The maximum number of characters that can be stored in \e dst.
1047  *
1048  * @note The parameter type string is copied to \e dst. \e dst is filled as if \c strncpy(dst, parameter_type, dst_len)
1049  *  were called. If the method contains no parameter with that index, \e dst is filled as
1050  *  if \c strncpy(dst, "", dst_len) were called.
1051  */
1052 OBJC_EXPORT void
1053 method_getArgumentType(Method _Nonnull m, unsigned int index,
1054                        char * _Nullable dst, size_t dst_len)
1055     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1056
1057 OBJC_EXPORT struct objc_method_description * _Nonnull
1058 method_getDescription(Method _Nonnull m)
1059     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1060
1061 /**
1062  * Sets the implementation of a method.
1063  *
1064  * @param m The method for which to set an implementation.
1065  * @param imp The implemention to set to this method.
1066  *
1067  * @return The previous implementation of the method.
1068  */
1069 OBJC_EXPORT IMP _Nonnull
1070 method_setImplementation(Method _Nonnull m, IMP _Nonnull imp)
1071     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1072
1073 /**
1074  * Exchanges the implementations of two methods.
1075  *
1076  * @param m1 Method to exchange with second method.
1077  * @param m2 Method to exchange with first method.
1078  *
1079  * @note This is an atomic version of the following:
1080  *  \code
1081  *  IMP imp1 = method_getImplementation(m1);
1082  *  IMP imp2 = method_getImplementation(m2);
1083  *  method_setImplementation(m1, imp2);
1084  *  method_setImplementation(m2, imp1);
1085  *  \endcode
1086  */
1087 OBJC_EXPORT void
1088 method_exchangeImplementations(Method _Nonnull m1, Method _Nonnull m2)
1089     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1090
1091
1092 /* Working with Instance Variables */
1093
1094 /**
1095  * Returns the name of an instance variable.
1096  *
1097  * @param v The instance variable you want to enquire about.
1098  *
1099  * @return A C string containing the instance variable's name.
1100  */
1101 OBJC_EXPORT const char * _Nullable
1102 ivar_getName(Ivar _Nonnull v)
1103     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1104
1105 /**
1106  * Returns the type string of an instance variable.
1107  *
1108  * @param v The instance variable you want to enquire about.
1109  *
1110  * @return A C string containing the instance variable's type encoding.
1111  *
1112  * @note For possible values, see Objective-C Runtime Programming Guide > Type Encodings.
1113  */
1114 OBJC_EXPORT const char * _Nullable
1115 ivar_getTypeEncoding(Ivar _Nonnull v)
1116     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1117
1118 /**
1119  * Returns the offset of an instance variable.
1120  *
1121  * @param v The instance variable you want to enquire about.
1122  *
1123  * @return The offset of \e v.
1124  *
1125  * @note For instance variables of type \c id or other object types, call \c object_getIvar
1126  *  and \c object_setIvar instead of using this offset to access the instance variable data directly.
1127  */
1128 OBJC_EXPORT ptrdiff_t
1129 ivar_getOffset(Ivar _Nonnull v)
1130     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1131
1132
1133 /* Working with Properties */
1134
1135 /**
1136  * Returns the name of a property.
1137  *
1138  * @param property The property you want to inquire about.
1139  *
1140  * @return A C string containing the property's name.
1141  */
1142 OBJC_EXPORT const char * _Nonnull
1143 property_getName(objc_property_t _Nonnull property)
1144     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1145
1146 /**
1147  * Returns the attribute string of a property.
1148  *
1149  * @param property A property.
1150  *
1151  * @return A C string containing the property's attributes.
1152  *
1153  * @note The format of the attribute string is described in Declared Properties in Objective-C Runtime Programming Guide.
1154  */
1155 OBJC_EXPORT const char * _Nullable
1156 property_getAttributes(objc_property_t _Nonnull property)
1157     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1158
1159 /**
1160  * Returns an array of property attributes for a property.
1161  *
1162  * @param property The property whose attributes you want copied.
1163  * @param outCount The number of attributes returned in the array.
1164  *
1165  * @return An array of property attributes; must be free'd() by the caller.
1166  */
1167 OBJC_EXPORT objc_property_attribute_t * _Nullable
1168 property_copyAttributeList(objc_property_t _Nonnull property,
1169                            unsigned int * _Nullable outCount)
1170     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1171
1172 /**
1173  * Returns the value of a property attribute given the attribute name.
1174  *
1175  * @param property The property whose attribute value you are interested in.
1176  * @param attributeName C string representing the attribute name.
1177  *
1178  * @return The value string of the attribute \e attributeName if it exists in
1179  *  \e property, \c nil otherwise.
1180  */
1181 OBJC_EXPORT char * _Nullable
1182 property_copyAttributeValue(objc_property_t _Nonnull property,
1183                             const char * _Nonnull attributeName)
1184     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1185
1186
1187 /* Working with Protocols */
1188
1189 /**
1190  * Returns a specified protocol.
1191  *
1192  * @param name The name of a protocol.
1193  *
1194  * @return The protocol named \e name, or \c NULL if no protocol named \e name could be found.
1195  *
1196  * @note This function acquires the runtime lock.
1197  */
1198 OBJC_EXPORT Protocol * _Nullable
1199 objc_getProtocol(const char * _Nonnull name)
1200     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1201
1202 /**
1203  * Returns an array of all the protocols known to the runtime.
1204  *
1205  * @param outCount Upon return, contains the number of protocols in the returned array.
1206  *
1207  * @return A C array of all the protocols known to the runtime. The array contains \c *outCount
1208  *  pointers followed by a \c NULL terminator. You must free the list with \c free().
1209  *
1210  * @note This function acquires the runtime lock.
1211  */
1212 OBJC_EXPORT Protocol * __unsafe_unretained _Nonnull * _Nullable
1213 objc_copyProtocolList(unsigned int * _Nullable outCount)
1214     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1215
1216 /**
1217  * Returns a Boolean value that indicates whether one protocol conforms to another protocol.
1218  *
1219  * @param proto A protocol.
1220  * @param other A protocol.
1221  *
1222  * @return \c YES if \e proto conforms to \e other, otherwise \c NO.
1223  *
1224  * @note One protocol can incorporate other protocols using the same syntax
1225  *  that classes use to adopt a protocol:
1226  *  \code
1227  *  @protocol ProtocolName < protocol list >
1228  *  \endcode
1229  *  All the protocols listed between angle brackets are considered part of the ProtocolName protocol.
1230  */
1231 OBJC_EXPORT BOOL
1232 protocol_conformsToProtocol(Protocol * _Nullable proto,
1233                             Protocol * _Nullable other)
1234     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1235
1236 /**
1237  * Returns a Boolean value that indicates whether two protocols are equal.
1238  *
1239  * @param proto A protocol.
1240  * @param other A protocol.
1241  *
1242  * @return \c YES if \e proto is the same as \e other, otherwise \c NO.
1243  */
1244 OBJC_EXPORT BOOL
1245 protocol_isEqual(Protocol * _Nullable proto, Protocol * _Nullable other)
1246     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1247
1248 /**
1249  * Returns the name of a protocol.
1250  *
1251  * @param proto A protocol.
1252  *
1253  * @return The name of the protocol \e p as a C string.
1254  */
1255 OBJC_EXPORT const char * _Nonnull
1256 protocol_getName(Protocol * _Nonnull proto)
1257     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1258
1259 /**
1260  * Returns a method description structure for a specified method of a given protocol.
1261  *
1262  * @param proto A protocol.
1263  * @param aSel A selector.
1264  * @param isRequiredMethod A Boolean value that indicates whether aSel is a required method.
1265  * @param isInstanceMethod A Boolean value that indicates whether aSel is an instance method.
1266  *
1267  * @return An \c objc_method_description structure that describes the method specified by \e aSel,
1268  *  \e isRequiredMethod, and \e isInstanceMethod for the protocol \e p.
1269  *  If the protocol does not contain the specified method, returns an \c objc_method_description structure
1270  *  with the value \c {NULL, \c NULL}.
1271  *
1272  * @note This function recursively searches any protocols that this protocol conforms to.
1273  */
1274 OBJC_EXPORT struct objc_method_description
1275 protocol_getMethodDescription(Protocol * _Nonnull proto, SEL _Nonnull aSel,
1276                               BOOL isRequiredMethod, BOOL isInstanceMethod)
1277     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1278
1279 /**
1280  * Returns an array of method descriptions of methods meeting a given specification for a given protocol.
1281  *
1282  * @param proto A protocol.
1283  * @param isRequiredMethod A Boolean value that indicates whether returned methods should
1284  *  be required methods (pass YES to specify required methods).
1285  * @param isInstanceMethod A Boolean value that indicates whether returned methods should
1286  *  be instance methods (pass YES to specify instance methods).
1287  * @param outCount Upon return, contains the number of method description structures in the returned array.
1288  *
1289  * @return A C array of \c objc_method_description structures containing the names and types of \e p's methods
1290  *  specified by \e isRequiredMethod and \e isInstanceMethod. The array contains \c *outCount pointers followed
1291  *  by a \c NULL terminator. You must free the list with \c free().
1292  *  If the protocol declares no methods that meet the specification, \c NULL is returned and \c *outCount is 0.
1293  *
1294  * @note Methods in other protocols adopted by this protocol are not included.
1295  */
1296 OBJC_EXPORT struct objc_method_description * _Nullable
1297 protocol_copyMethodDescriptionList(Protocol * _Nonnull proto,
1298                                    BOOL isRequiredMethod,
1299                                    BOOL isInstanceMethod,
1300                                    unsigned int * _Nullable outCount)
1301     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1302
1303 /**
1304  * Returns the specified property of a given protocol.
1305  *
1306  * @param proto A protocol.
1307  * @param name The name of a property.
1308  * @param isRequiredProperty \c YES searches for a required property, \c NO searches for an optional property.
1309  * @param isInstanceProperty \c YES searches for an instance property, \c NO searches for a class property.
1310  *
1311  * @return The property specified by \e name, \e isRequiredProperty, and \e isInstanceProperty for \e proto,
1312  *  or \c NULL if none of \e proto's properties meets the specification.
1313  */
1314 OBJC_EXPORT objc_property_t _Nullable
1315 protocol_getProperty(Protocol * _Nonnull proto,
1316                      const char * _Nonnull name,
1317                      BOOL isRequiredProperty, BOOL isInstanceProperty)
1318     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1319
1320 /**
1321  * Returns an array of the required instance properties declared by a protocol.
1322  *
1323  * @note Identical to
1324  * \code
1325  * protocol_copyPropertyList2(proto, outCount, YES, YES);
1326  * \endcode
1327  */
1328 OBJC_EXPORT objc_property_t _Nonnull * _Nullable
1329 protocol_copyPropertyList(Protocol * _Nonnull proto,
1330                           unsigned int * _Nullable outCount)
1331     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1332
1333 /**
1334  * Returns an array of properties declared by a protocol.
1335  *
1336  * @param proto A protocol.
1337  * @param outCount Upon return, contains the number of elements in the returned array.
1338  * @param isRequiredProperty \c YES returns required properties, \c NO returns optional properties.
1339  * @param isInstanceProperty \c YES returns instance properties, \c NO returns class properties.
1340  *
1341  * @return A C array of pointers of type \c objc_property_t describing the properties declared by \e proto.
1342  *  Any properties declared by other protocols adopted by this protocol are not included. The array contains
1343  *  \c *outCount pointers followed by a \c NULL terminator. You must free the array with \c free().
1344  *  If the protocol declares no matching properties, \c NULL is returned and \c *outCount is \c 0.
1345  */
1346 OBJC_EXPORT objc_property_t _Nonnull * _Nullable
1347 protocol_copyPropertyList2(Protocol * _Nonnull proto,
1348                            unsigned int * _Nullable outCount,
1349                            BOOL isRequiredProperty, BOOL isInstanceProperty)
1350     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
1351
1352 /**
1353  * Returns an array of the protocols adopted by a protocol.
1354  *
1355  * @param proto A protocol.
1356  * @param outCount Upon return, contains the number of elements in the returned array.
1357  *
1358  * @return A C array of protocols adopted by \e proto. The array contains \e *outCount pointers
1359  *  followed by a \c NULL terminator. You must free the array with \c free().
1360  *  If the protocol declares no properties, \c NULL is returned and \c *outCount is \c 0.
1361  */
1362 OBJC_EXPORT Protocol * __unsafe_unretained _Nonnull * _Nullable
1363 protocol_copyProtocolList(Protocol * _Nonnull proto,
1364                           unsigned int * _Nullable outCount)
1365     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1366
1367 /**
1368  * Creates a new protocol instance that cannot be used until registered with
1369  * \c objc_registerProtocol()
1370  *
1371  * @param name The name of the protocol to create.
1372  *
1373  * @return The Protocol instance on success, \c nil if a protocol
1374  *  with the same name already exists.
1375  * @note There is no dispose method for this.
1376  */
1377 OBJC_EXPORT Protocol * _Nullable
1378 objc_allocateProtocol(const char * _Nonnull name)
1379     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1380
1381 /**
1382  * Registers a newly constructed protocol with the runtime. The protocol
1383  * will be ready for use and is immutable after this.
1384  *
1385  * @param proto The protocol you want to register.
1386  */
1387 OBJC_EXPORT void
1388 objc_registerProtocol(Protocol * _Nonnull proto)
1389     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1390
1391 /**
1392  * Adds a method to a protocol. The protocol must be under construction.
1393  *
1394  * @param proto The protocol to add a method to.
1395  * @param name The name of the method to add.
1396  * @param types A C string that represents the method signature.
1397  * @param isRequiredMethod YES if the method is not an optional method.
1398  * @param isInstanceMethod YES if the method is an instance method.
1399  */
1400 OBJC_EXPORT void
1401 protocol_addMethodDescription(Protocol * _Nonnull proto, SEL _Nonnull name,
1402                               const char * _Nullable types,
1403                               BOOL isRequiredMethod, BOOL isInstanceMethod)
1404     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1405
1406 /**
1407  * Adds an incorporated protocol to another protocol. The protocol being
1408  * added to must still be under construction, while the additional protocol
1409  * must be already constructed.
1410  *
1411  * @param proto The protocol you want to add to, it must be under construction.
1412  * @param addition The protocol you want to incorporate into \e proto, it must be registered.
1413  */
1414 OBJC_EXPORT void
1415 protocol_addProtocol(Protocol * _Nonnull proto, Protocol * _Nonnull addition)
1416     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1417
1418 /**
1419  * Adds a property to a protocol. The protocol must be under construction.
1420  *
1421  * @param proto The protocol to add a property to.
1422  * @param name The name of the property.
1423  * @param attributes An array of property attributes.
1424  * @param attributeCount The number of attributes in \e attributes.
1425  * @param isRequiredProperty YES if the property (accessor methods) is not optional.
1426  * @param isInstanceProperty YES if the property (accessor methods) are instance methods.
1427  *  This is the only case allowed fo a property, as a result, setting this to NO will
1428  *  not add the property to the protocol at all.
1429  */
1430 OBJC_EXPORT void
1431 protocol_addProperty(Protocol * _Nonnull proto, const char * _Nonnull name,
1432                      const objc_property_attribute_t * _Nullable attributes,
1433                      unsigned int attributeCount,
1434                      BOOL isRequiredProperty, BOOL isInstanceProperty)
1435     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1436
1437
1438 /* Working with Libraries */
1439
1440 /**
1441  * Returns the names of all the loaded Objective-C frameworks and dynamic
1442  * libraries.
1443  *
1444  * @param outCount The number of names returned.
1445  *
1446  * @return An array of C strings of names. Must be free()'d by caller.
1447  */
1448 OBJC_EXPORT const char * _Nonnull * _Nonnull
1449 objc_copyImageNames(unsigned int * _Nullable outCount)
1450     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1451
1452 /**
1453  * Returns the dynamic library name a class originated from.
1454  *
1455  * @param cls The class you are inquiring about.
1456  *
1457  * @return The name of the library containing this class.
1458  */
1459 OBJC_EXPORT const char * _Nullable
1460 class_getImageName(Class _Nullable cls)
1461     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1462
1463 /**
1464  * Returns the names of all the classes within a library.
1465  *
1466  * @param image The library or framework you are inquiring about.
1467  * @param outCount The number of class names returned.
1468  *
1469  * @return An array of C strings representing the class names.
1470  */
1471 OBJC_EXPORT const char * _Nonnull * _Nullable
1472 objc_copyClassNamesForImage(const char * _Nonnull image,
1473                             unsigned int * _Nullable outCount)
1474     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1475
1476
1477 /* Working with Selectors */
1478
1479 /**
1480  * Returns the name of the method specified by a given selector.
1481  *
1482  * @param sel A pointer of type \c SEL. Pass the selector whose name you wish to determine.
1483  *
1484  * @return A C string indicating the name of the selector.
1485  */
1486 OBJC_EXPORT const char * _Nonnull
1487 sel_getName(SEL _Nonnull sel)
1488     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
1489
1490
1491 /**
1492  * Registers a method with the Objective-C runtime system, maps the method
1493  * name to a selector, and returns the selector value.
1494  *
1495  * @param str A pointer to a C string. Pass the name of the method you wish to register.
1496  *
1497  * @return A pointer of type SEL specifying the selector for the named method.
1498  *
1499  * @note You must register a method name with the Objective-C runtime system to obtain the
1500  *  method’s selector before you can add the method to a class definition. If the method name
1501  *  has already been registered, this function simply returns the selector.
1502  */
1503 OBJC_EXPORT SEL _Nonnull
1504 sel_registerName(const char * _Nonnull str)
1505     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
1506
1507 /**
1508  * Returns a Boolean value that indicates whether two selectors are equal.
1509  *
1510  * @param lhs The selector to compare with rhs.
1511  * @param rhs The selector to compare with lhs.
1512  *
1513  * @return \c YES if \e lhs and \e rhs are equal, otherwise \c NO.
1514  *
1515  * @note sel_isEqual is equivalent to ==.
1516  */
1517 OBJC_EXPORT BOOL
1518 sel_isEqual(SEL _Nonnull lhs, SEL _Nonnull rhs)
1519     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1520
1521
1522 /* Objective-C Language Features */
1523
1524 /**
1525  * This function is inserted by the compiler when a mutation
1526  * is detected during a foreach iteration. It gets called
1527  * when a mutation occurs, and the enumerationMutationHandler
1528  * is enacted if it is set up. A fatal error occurs if a handler is not set up.
1529  *
1530  * @param obj The object being mutated.
1531  *
1532  */
1533 OBJC_EXPORT void
1534 objc_enumerationMutation(id _Nonnull obj)
1535     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1536
1537 /**
1538  * Sets the current mutation handler.
1539  *
1540  * @param handler Function pointer to the new mutation handler.
1541  */
1542 OBJC_EXPORT void
1543 objc_setEnumerationMutationHandler(void (*_Nullable handler)(id _Nonnull ))
1544     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1545
1546 /**
1547  * Set the function to be called by objc_msgForward.
1548  *
1549  * @param fwd Function to be jumped to by objc_msgForward.
1550  * @param fwd_stret Function to be jumped to by objc_msgForward_stret.
1551  *
1552  * @see message.h::_objc_msgForward
1553  */
1554 OBJC_EXPORT void
1555 objc_setForwardHandler(void * _Nonnull fwd, void * _Nonnull fwd_stret)
1556     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
1557
1558 /**
1559  * Creates a pointer to a function that will call the block
1560  * when the method is called.
1561  *
1562  * @param block The block that implements this method. Its signature should
1563  *  be: method_return_type ^(id self, method_args...).
1564  *  The selector is not available as a parameter to this block.
1565  *  The block is copied with \c Block_copy().
1566  *
1567  * @return The IMP that calls this block. Must be disposed of with
1568  *  \c imp_removeBlock.
1569  */
1570 OBJC_EXPORT IMP _Nonnull
1571 imp_implementationWithBlock(id _Nonnull block)
1572     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1573
1574 /**
1575  * Return the block associated with an IMP that was created using
1576  * \c imp_implementationWithBlock.
1577  *
1578  * @param anImp The IMP that calls this block.
1579  *
1580  * @return The block called by \e anImp.
1581  */
1582 OBJC_EXPORT id _Nullable
1583 imp_getBlock(IMP _Nonnull anImp)
1584     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1585
1586 /**
1587  * Disassociates a block from an IMP that was created using
1588  * \c imp_implementationWithBlock and releases the copy of the
1589  * block that was created.
1590  *
1591  * @param anImp An IMP that was created using \c imp_implementationWithBlock.
1592  *
1593  * @return YES if the block was released successfully, NO otherwise.
1594  *  (For example, the block might not have been used to create an IMP previously).
1595  */
1596 OBJC_EXPORT BOOL
1597 imp_removeBlock(IMP _Nonnull anImp)
1598     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
1599
1600 /**
1601  * This loads the object referenced by a weak pointer and returns it, after
1602  * retaining and autoreleasing the object to ensure that it stays alive
1603  * long enough for the caller to use it. This function would be used
1604  * anywhere a __weak variable is used in an expression.
1605  *
1606  * @param location The weak pointer address
1607  *
1608  * @return The object pointed to by \e location, or \c nil if \e *location is \c nil.
1609  */
1610 OBJC_EXPORT id _Nullable
1611 objc_loadWeak(id _Nullable * _Nonnull location)
1612     OBJC_AVAILABLE(10.7, 5.0, 9.0, 1.0, 2.0);
1613
1614 /**
1615  * This function stores a new value into a __weak variable. It would
1616  * be used anywhere a __weak variable is the target of an assignment.
1617  *
1618  * @param location The address of the weak pointer itself
1619  * @param obj The new object this weak ptr should now point to
1620  *
1621  * @return The value stored into \e location, i.e. \e obj
1622  */
1623 OBJC_EXPORT id _Nullable
1624 objc_storeWeak(id _Nullable * _Nonnull location, id _Nullable obj)
1625     OBJC_AVAILABLE(10.7, 5.0, 9.0, 1.0, 2.0);
1626
1627
1628 /* Associative References */
1629
1630 /**
1631  * Policies related to associative references.
1632  * These are options to objc_setAssociatedObject()
1633  */
1634 typedef OBJC_ENUM(uintptr_t, objc_AssociationPolicy) {
1635     OBJC_ASSOCIATION_ASSIGN = 0,           /**< Specifies a weak reference to the associated object. */
1636     OBJC_ASSOCIATION_RETAIN_NONATOMIC = 1, /**< Specifies a strong reference to the associated object.
1637                                             *   The association is not made atomically. */
1638     OBJC_ASSOCIATION_COPY_NONATOMIC = 3,   /**< Specifies that the associated object is copied.
1639                                             *   The association is not made atomically. */
1640     OBJC_ASSOCIATION_RETAIN = 01401,       /**< Specifies a strong reference to the associated object.
1641                                             *   The association is made atomically. */
1642     OBJC_ASSOCIATION_COPY = 01403          /**< Specifies that the associated object is copied.
1643                                             *   The association is made atomically. */
1644 };
1645
1646 /**
1647  * Sets an associated value for a given object using a given key and association policy.
1648  *
1649  * @param object The source object for the association.
1650  * @param key The key for the association.
1651  * @param value The value to associate with the key key for object. Pass nil to clear an existing association.
1652  * @param policy The policy for the association. For possible values, see “Associative Object Behaviors.”
1653  *
1654  * @see objc_setAssociatedObject
1655  * @see objc_removeAssociatedObjects
1656  */
1657 OBJC_EXPORT void
1658 objc_setAssociatedObject(id _Nonnull object, const void * _Nonnull key,
1659                          id _Nullable value, objc_AssociationPolicy policy)
1660     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0, 2.0);
1661
1662 /**
1663  * Returns the value associated with a given object for a given key.
1664  *
1665  * @param object The source object for the association.
1666  * @param key The key for the association.
1667  *
1668  * @return The value associated with the key \e key for \e object.
1669  *
1670  * @see objc_setAssociatedObject
1671  */
1672 OBJC_EXPORT id _Nullable
1673 objc_getAssociatedObject(id _Nonnull object, const void * _Nonnull key)
1674     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0, 2.0);
1675
1676 /**
1677  * Removes all associations for a given object.
1678  *
1679  * @param object An object that maintains associated objects.
1680  *
1681  * @note The main purpose of this function is to make it easy to return an object
1682  *  to a "pristine state”. You should not use this function for general removal of
1683  *  associations from objects, since it also removes associations that other clients
1684  *  may have added to the object. Typically you should use \c objc_setAssociatedObject
1685  *  with a nil value to clear an association.
1686  *
1687  * @see objc_setAssociatedObject
1688  * @see objc_getAssociatedObject
1689  */
1690 OBJC_EXPORT void
1691 objc_removeAssociatedObjects(id _Nonnull object)
1692     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0, 2.0);
1693
1694
1695 /* Hooks for Swift */
1696
1697 /**
1698  * Function type for a hook that intercepts class_getImageName().
1699  *
1700  * @param cls The class whose image name is being looked up.
1701  * @param outImageName On return, the result of the image name lookup.
1702  * @return YES if an image name for this class was found, NO otherwise.
1703  *
1704  * @see class_getImageName
1705  * @see objc_setHook_getImageName
1706  */
1707 typedef BOOL (*objc_hook_getImageName)(Class _Nonnull cls, const char * _Nullable * _Nonnull outImageName);
1708
1709 /**
1710  * Install a hook for class_getImageName().
1711  *
1712  * @param newValue The hook function to install.
1713  * @param outOldValue The address of a function pointer variable. On return,
1714  *  the old hook function is stored in the variable.
1715  *
1716  * @note The store to *outOldValue is thread-safe: the variable will be
1717  *  updated before class_getImageName() calls your new hook to read it,
1718  *  even if your new hook is called from another thread before this
1719  *  setter completes.
1720  * @note The first hook in the chain is the native implementation of
1721  *  class_getImageName(). Your hook should call the previous hook for
1722  *  classes that you do not recognize.
1723  *
1724  * @see class_getImageName
1725  * @see objc_hook_getImageName
1726  */
1727 OBJC_EXPORT void objc_setHook_getImageName(objc_hook_getImageName _Nonnull newValue,
1728                                            objc_hook_getImageName _Nullable * _Nonnull outOldValue)
1729     OBJC_AVAILABLE(10.14, 12.0, 12.0, 5.0, 3.0);
1730
1731
1732 #define _C_ID       '@'
1733 #define _C_CLASS    '#'
1734 #define _C_SEL      ':'
1735 #define _C_CHR      'c'
1736 #define _C_UCHR     'C'
1737 #define _C_SHT      's'
1738 #define _C_USHT     'S'
1739 #define _C_INT      'i'
1740 #define _C_UINT     'I'
1741 #define _C_LNG      'l'
1742 #define _C_ULNG     'L'
1743 #define _C_LNG_LNG  'q'
1744 #define _C_ULNG_LNG 'Q'
1745 #define _C_FLT      'f'
1746 #define _C_DBL      'd'
1747 #define _C_BFLD     'b'
1748 #define _C_BOOL     'B'
1749 #define _C_VOID     'v'
1750 #define _C_UNDEF    '?'
1751 #define _C_PTR      '^'
1752 #define _C_CHARPTR  '*'
1753 #define _C_ATOM     '%'
1754 #define _C_ARY_B    '['
1755 #define _C_ARY_E    ']'
1756 #define _C_UNION_B  '('
1757 #define _C_UNION_E  ')'
1758 #define _C_STRUCT_B '{'
1759 #define _C_STRUCT_E '}'
1760 #define _C_VECTOR   '!'
1761 #define _C_CONST    'r'
1762
1763
1764 /* Obsolete types */
1765
1766 #if !__OBJC2__
1767
1768 #define CLS_GETINFO(cls,infomask)        ((cls)->info & (infomask))
1769 #define CLS_SETINFO(cls,infomask)        ((cls)->info |= (infomask))
1770
1771 // class is not a metaclass
1772 #define CLS_CLASS               0x1
1773 // class is a metaclass
1774 #define CLS_META                0x2
1775 // class's +initialize method has completed
1776 #define CLS_INITIALIZED         0x4
1777 // class is posing
1778 #define CLS_POSING              0x8
1779 // unused
1780 #define CLS_MAPPED              0x10
1781 // class and subclasses need cache flush during image loading
1782 #define CLS_FLUSH_CACHE         0x20
1783 // method cache should grow when full
1784 #define CLS_GROW_CACHE          0x40
1785 // unused
1786 #define CLS_NEED_BIND           0x80
1787 // methodLists is array of method lists
1788 #define CLS_METHOD_ARRAY        0x100
1789 // the JavaBridge constructs classes with these markers
1790 #define CLS_JAVA_HYBRID         0x200
1791 #define CLS_JAVA_CLASS          0x400
1792 // thread-safe +initialize
1793 #define CLS_INITIALIZING        0x800
1794 // bundle unloading
1795 #define CLS_FROM_BUNDLE         0x1000
1796 // C++ ivar support
1797 #define CLS_HAS_CXX_STRUCTORS   0x2000
1798 // Lazy method list arrays
1799 #define CLS_NO_METHOD_ARRAY     0x4000
1800 // +load implementation
1801 #define CLS_HAS_LOAD_METHOD     0x8000
1802 // objc_allocateClassPair API
1803 #define CLS_CONSTRUCTING        0x10000
1804 // class compiled with bigger class structure
1805 #define CLS_EXT                 0x20000
1806
1807
1808 struct objc_method_description_list {
1809     int count;
1810     struct objc_method_description list[1];
1811 };
1812
1813
1814 struct objc_protocol_list {
1815     struct objc_protocol_list * _Nullable next;
1816     long count;
1817     __unsafe_unretained Protocol * _Nullable list[1];
1818 };
1819
1820
1821 struct objc_category {
1822     char * _Nonnull category_name                            OBJC2_UNAVAILABLE;
1823     char * _Nonnull class_name                               OBJC2_UNAVAILABLE;
1824     struct objc_method_list * _Nullable instance_methods     OBJC2_UNAVAILABLE;
1825     struct objc_method_list * _Nullable class_methods        OBJC2_UNAVAILABLE;
1826     struct objc_protocol_list * _Nullable protocols          OBJC2_UNAVAILABLE;
1827 }                                                            OBJC2_UNAVAILABLE;
1828
1829
1830 struct objc_ivar {
1831     char * _Nullable ivar_name                               OBJC2_UNAVAILABLE;
1832     char * _Nullable ivar_type                               OBJC2_UNAVAILABLE;
1833     int ivar_offset                                          OBJC2_UNAVAILABLE;
1834 #ifdef __LP64__
1835     int space                                                OBJC2_UNAVAILABLE;
1836 #endif
1837 }                                                            OBJC2_UNAVAILABLE;
1838
1839 struct objc_ivar_list {
1840     int ivar_count                                           OBJC2_UNAVAILABLE;
1841 #ifdef __LP64__
1842     int space                                                OBJC2_UNAVAILABLE;
1843 #endif
1844     /* variable length structure */
1845     struct objc_ivar ivar_list[1]                            OBJC2_UNAVAILABLE;
1846 }                                                            OBJC2_UNAVAILABLE;
1847
1848
1849 struct objc_method {
1850     SEL _Nonnull method_name                                 OBJC2_UNAVAILABLE;
1851     char * _Nullable method_types                            OBJC2_UNAVAILABLE;
1852     IMP _Nonnull method_imp                                  OBJC2_UNAVAILABLE;
1853 }                                                            OBJC2_UNAVAILABLE;
1854
1855 struct objc_method_list {
1856     struct objc_method_list * _Nullable obsolete             OBJC2_UNAVAILABLE;
1857
1858     int method_count                                         OBJC2_UNAVAILABLE;
1859 #ifdef __LP64__
1860     int space                                                OBJC2_UNAVAILABLE;
1861 #endif
1862     /* variable length structure */
1863     struct objc_method method_list[1]                        OBJC2_UNAVAILABLE;
1864 }                                                            OBJC2_UNAVAILABLE;
1865
1866
1867 typedef struct objc_symtab *Symtab                           OBJC2_UNAVAILABLE;
1868
1869 struct objc_symtab {
1870     unsigned long sel_ref_cnt                                OBJC2_UNAVAILABLE;
1871     SEL _Nonnull * _Nullable refs                            OBJC2_UNAVAILABLE;
1872     unsigned short cls_def_cnt                               OBJC2_UNAVAILABLE;
1873     unsigned short cat_def_cnt                               OBJC2_UNAVAILABLE;
1874     void * _Nullable defs[1] /* variable size */             OBJC2_UNAVAILABLE;
1875 }                                                            OBJC2_UNAVAILABLE;
1876
1877
1878 typedef struct objc_cache *Cache                             OBJC2_UNAVAILABLE;
1879
1880 #define CACHE_BUCKET_NAME(B)  ((B)->method_name)
1881 #define CACHE_BUCKET_IMP(B)   ((B)->method_imp)
1882 #define CACHE_BUCKET_VALID(B) (B)
1883 #ifndef __LP64__
1884 #define CACHE_HASH(sel, mask) (((uintptr_t)(sel)>>2) & (mask))
1885 #else
1886 #define CACHE_HASH(sel, mask) (((unsigned int)((uintptr_t)(sel)>>3)) & (mask))
1887 #endif
1888 struct objc_cache {
1889     unsigned int mask /* total = mask + 1 */                 OBJC2_UNAVAILABLE;
1890     unsigned int occupied                                    OBJC2_UNAVAILABLE;
1891     Method _Nullable buckets[1]                              OBJC2_UNAVAILABLE;
1892 };
1893
1894
1895 typedef struct objc_module *Module                           OBJC2_UNAVAILABLE;
1896
1897 struct objc_module {
1898     unsigned long version                                    OBJC2_UNAVAILABLE;
1899     unsigned long size                                       OBJC2_UNAVAILABLE;
1900     const char * _Nullable name                              OBJC2_UNAVAILABLE;
1901     Symtab _Nullable symtab                                  OBJC2_UNAVAILABLE;
1902 }                                                            OBJC2_UNAVAILABLE;
1903
1904 #else
1905
1906 struct objc_method_list;
1907
1908 #endif
1909
1910
1911 /* Obsolete functions */
1912
1913 OBJC_EXPORT IMP _Nullable
1914 class_lookupMethod(Class _Nullable cls, SEL _Nonnull sel)
1915     __OSX_DEPRECATED(10.0, 10.5, "use class_getMethodImplementation instead")
1916     __IOS_DEPRECATED(2.0, 2.0, "use class_getMethodImplementation instead")
1917     __TVOS_DEPRECATED(9.0, 9.0, "use class_getMethodImplementation instead")
1918     __WATCHOS_DEPRECATED(1.0, 1.0, "use class_getMethodImplementation instead")
1919     __BRIDGEOS_DEPRECATED(2.0, 2.0, "use class_getMethodImplementation instead");
1920 OBJC_EXPORT BOOL
1921 class_respondsToMethod(Class _Nullable cls, SEL _Nonnull sel)
1922     __OSX_DEPRECATED(10.0, 10.5, "use class_respondsToSelector instead")
1923     __IOS_DEPRECATED(2.0, 2.0, "use class_respondsToSelector instead")
1924     __TVOS_DEPRECATED(9.0, 9.0, "use class_respondsToSelector instead")
1925     __WATCHOS_DEPRECATED(1.0, 1.0, "use class_respondsToSelector instead")
1926     __BRIDGEOS_DEPRECATED(2.0, 2.0, "use class_respondsToSelector instead");
1927
1928 OBJC_EXPORT void
1929 _objc_flush_caches(Class _Nullable cls)
1930     __OSX_DEPRECATED(10.0, 10.5, "not recommended")
1931     __IOS_DEPRECATED(2.0, 2.0, "not recommended")
1932     __TVOS_DEPRECATED(9.0, 9.0, "not recommended")
1933     __WATCHOS_DEPRECATED(1.0, 1.0, "not recommended")
1934     __BRIDGEOS_DEPRECATED(2.0, 2.0, "not recommended");
1935
1936 OBJC_EXPORT id _Nullable
1937 object_copyFromZone(id _Nullable anObject, size_t nBytes, void * _Nullable z)
1938     __OSX_DEPRECATED(10.0, 10.5, "use object_copy instead")
1939     __IOS_UNAVAILABLE __TVOS_UNAVAILABLE
1940     __WATCHOS_UNAVAILABLE __BRIDGEOS_UNAVAILABLE
1941     OBJC_ARC_UNAVAILABLE;
1942
1943 OBJC_EXPORT id _Nullable
1944 object_realloc(id _Nullable anObject, size_t nBytes)
1945     OBJC2_UNAVAILABLE;
1946
1947 OBJC_EXPORT id _Nullable
1948 object_reallocFromZone(id _Nullable anObject, size_t nBytes, void * _Nullable z)
1949     OBJC2_UNAVAILABLE;
1950
1951 #define OBSOLETE_OBJC_GETCLASSES 1
1952 OBJC_EXPORT void * _Nonnull
1953 objc_getClasses(void)
1954     OBJC2_UNAVAILABLE;
1955
1956 OBJC_EXPORT void
1957 objc_addClass(Class _Nonnull myClass)
1958     OBJC2_UNAVAILABLE;
1959
1960 OBJC_EXPORT void
1961 objc_setClassHandler(int (* _Nullable )(const char * _Nonnull))
1962     OBJC2_UNAVAILABLE;
1963
1964 OBJC_EXPORT void
1965 objc_setMultithreaded(BOOL flag)
1966     OBJC2_UNAVAILABLE;
1967
1968 OBJC_EXPORT id _Nullable
1969 class_createInstanceFromZone(Class _Nullable, size_t idxIvars,
1970                              void * _Nullable z)
1971     __OSX_DEPRECATED(10.0, 10.5, "use class_createInstance instead")
1972     __IOS_UNAVAILABLE __TVOS_UNAVAILABLE
1973     __WATCHOS_UNAVAILABLE __BRIDGEOS_UNAVAILABLE
1974     OBJC_ARC_UNAVAILABLE;
1975
1976 OBJC_EXPORT void
1977 class_addMethods(Class _Nullable, struct objc_method_list * _Nonnull)
1978     OBJC2_UNAVAILABLE;
1979
1980 OBJC_EXPORT void
1981 class_removeMethods(Class _Nullable, struct objc_method_list * _Nonnull)
1982     OBJC2_UNAVAILABLE;
1983
1984 OBJC_EXPORT void
1985 _objc_resolve_categories_for_class(Class _Nonnull cls)
1986     OBJC2_UNAVAILABLE;
1987
1988 OBJC_EXPORT Class _Nonnull
1989 class_poseAs(Class _Nonnull imposter, Class _Nonnull original)
1990     OBJC2_UNAVAILABLE;
1991
1992 OBJC_EXPORT unsigned int
1993 method_getSizeOfArguments(Method _Nonnull m)
1994     OBJC2_UNAVAILABLE;
1995
1996 OBJC_EXPORT unsigned
1997 method_getArgumentInfo(struct objc_method * _Nonnull m, int arg,
1998                        const char * _Nullable * _Nonnull type,
1999                        int * _Nonnull offset)
2000     UNAVAILABLE_ATTRIBUTE  // This function was accidentally deleted in 10.9.
2001     OBJC2_UNAVAILABLE;
2002
2003 OBJC_EXPORT Class _Nullable
2004 objc_getOrigClass(const char * _Nonnull name)
2005     OBJC2_UNAVAILABLE;
2006
2007 #define OBJC_NEXT_METHOD_LIST 1
2008 OBJC_EXPORT struct objc_method_list * _Nullable
2009 class_nextMethodList(Class _Nullable, void * _Nullable * _Nullable)
2010     OBJC2_UNAVAILABLE;
2011 // usage for nextMethodList
2012 //
2013 // void *iterator = 0;
2014 // struct objc_method_list *mlist;
2015 // while ( mlist = class_nextMethodList( cls, &iterator ) )
2016 //    ;
2017
2018 OBJC_EXPORT id _Nullable
2019 (* _Nonnull _alloc)(Class _Nullable, size_t)
2020     OBJC2_UNAVAILABLE;
2021
2022 OBJC_EXPORT id _Nullable
2023 (* _Nonnull _copy)(id _Nullable, size_t)
2024      OBJC2_UNAVAILABLE;
2025
2026 OBJC_EXPORT id _Nullable
2027 (* _Nonnull _realloc)(id _Nullable, size_t)
2028      OBJC2_UNAVAILABLE;
2029
2030 OBJC_EXPORT id _Nullable
2031 (* _Nonnull _dealloc)(id _Nullable)
2032      OBJC2_UNAVAILABLE;
2033
2034 OBJC_EXPORT id _Nullable
2035 (* _Nonnull _zoneAlloc)(Class _Nullable, size_t, void * _Nullable)
2036      OBJC2_UNAVAILABLE;
2037
2038 OBJC_EXPORT id _Nullable
2039 (* _Nonnull _zoneRealloc)(id _Nullable, size_t, void * _Nullable)
2040      OBJC2_UNAVAILABLE;
2041
2042 OBJC_EXPORT id _Nullable
2043 (* _Nonnull _zoneCopy)(id _Nullable, size_t, void * _Nullable)
2044      OBJC2_UNAVAILABLE;
2045
2046 OBJC_EXPORT void
2047 (* _Nonnull _error)(id _Nullable, const char * _Nonnull, va_list)
2048      OBJC2_UNAVAILABLE;
2049
2050 #endif