BridgeSupport man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

BRIDGESUPPORT(5)	    BSD File Formats Manual	      BRIDGESUPPORT(5)

NAME
     BridgeSupport — Scripting bridges support file

DESCRIPTION
     BridgeSupport files are XML files that describe the API symbols of frame‐
     works or libraries that cannot be introspected at runtime. These are gen‐
     erally ANSI C symbols that are non-object-oriented items such as con‐
     stants, enumerations, structures, and functions but can also include some
     additional information about classes, methods, and informal protocols.

     BridgeSupport files are a major component of the Objective-C bridges
     (RubyCocoa and PyObjC) supported in Mac OS X for scripting languages such
     as Ruby and Python.

     gen_bridge_metadata(1) is the tool used to generate BridgeSupport files
     for particular frameworks or libraries.

     To understand the following discussion you should know what “element” and
     “attribute” mean in XML markup. You should also be familiar with Objec‐
     tive-C and with concepts related to the Objective-C runtime, such as the
     type-encoding constants.

     As of Mac OS 10.7, BridgeSupport uses an improved parser, based on clang.
     This means the BridgeSupport files should be more correct and complete,
     and the true parsing allows the automatic extraction of metadata from
     existing __attribute__() information supported by the compiler (see
     below).

STRUCTURE
     The structure of  BridgeSupport XML consists of a hierarchy of elements
     under the root element, signatures.

   The signatures element
     signatures is the top-level, or root, element of a BridgeSupport XML
     file.

     Mandatory attributes:

     version  The version number of the BridgeSupport format. The only possi‐
	      ble value is “1.0” which means the format delivered with Mac OS
	      X 10.5.

     Possible children elements: depends_on, struct, cftype, opaque, constant,
     string_constant, enum, function, function_alias, informal_protocol,
     class.

   The depends_on element
     This element describes a dependency. Frameworks usually depend on other
     frameworks, and the bridges will use these elements to interpret the
     BridgeSupport files of the dependencies before interpreting the given
     one.

     Mandatory attributes:

     path  The path of the dependency.

   The struct element
     This element describes a C structure.

     Mandatory attributes:

     name	   The name of the C structure.

     type, type64  The complete type of the C structure, including the field
		   names, as a string of Objective-C runtime encoding types.
		   If the element has a different type on a 64-bit environ‐
		   ment, the type64 attribute will contain it. If the element
		   does not exist on a 32-bit environment, only the type64
		   attribute will be used.

     Optional attributes:

     opaque  Indicates whether the fields of the structure should be exposed.
	     The default value is “false”.

   The cftype element
     This element describes a Core Foundation-based type.

     Mandatory attributes:

     name	   The name of the Core Foundation type.

     type, type64  The type of the Core Foundation type as a string of Objec‐
		   tive-C runtime encoding types. If the element has a differ‐
		   ent type on a 64-bit environment, the type64 attribute will
		   contain it. If the element does not exist on a 32-bit envi‐
		   ronment, only the type64 attribute will be used.

     Optional attributes:

     tollfree	     The name of the tollfree-bridged Objective-C class, if
		     any.

     gettypeid_func  The name of the function that retrieves the TypeID value
		     of the given Core Foundation type, if any. This name usu‐
		     ally ends with “GetTypeID”.

   The opaque element
     This element describes an opaque type, most generally a C pointer to a C
     opaque structure.

     Mandatory attributes:

     name	   The name of the opaque type.

     type, type64  The type of the opaque type, as a string of Objective-C
		   runtime encoding types. If the element has a different type
		   on a 64-bit environment, the type64 attribute will contain
		   it. If the element does not exist on a 32-bit environment,
		   only the type64 attribute will be used.

   The constant element
     This element describes a C constant.

     Mandatory attributes:

     name	   The name of the C constant.

     type, type64  The type of the C constant, as a string of Objective-C run‐
		   time encoding types. If the element has a different type on
		   a 64-bit environment, the type64 attribute will contain it.
		   If the element does not exist on a 32-bit environment, only
		   the type64 attribute will be used.

     Optional attributes:

     magic_cookie  Indicates whether the C constant has a “magic” or fixed
		   value and should not be converted at runtime to the given
		   type. The default value is “false”.

   The string_constant element
     This element describes a string constant. The string can either be a C
     string or an Objective-C string (an NSString object).  string_constant
     elements are usually created from C preprocessor macros.

     Mandatory attributes:

     name   The name of the string constant.

     value  The value of the string constant.

     Optional attributes:

     nsstring  Indicates whether the string constant has an Objective-C value,
	       and should be converted to an NSString object. The default
	       value is “false”.

   The enum element
     This element describes a C enumeration.

     Mandatory attributes:

     name  The name of the C enumeration.

     value, value64
	   The value of the C enumeration, as an integer. The value can be
	   negative. If the enumeration has a different value on a 64-bit
	   environment, the value64 attribute will contain it. If the enumera‐
	   tion does not exist on a 32-bit environment, only the value64
	   attribute will be used.  (The le_value and be_value values for lit‐
	   tle and big endian platforms are no longer supported; only native,
	   little endian order is now used.)

     Optional attributes:

     ignore	 Indicates whether the C enumeration should be ignored by the
		 bridges. The default value is “false”.

     suggestion	 If the ignore attribute is “true” , this attribute may con‐
		 tain a textual message that the bridges can deliver as an
		 exception or error message to be delivered to the user. By
		 default there is no suggestion.

   The function element
     This element describes a C function.

     Mandatory attributes:

     name  The name of the C function.

     Optional attributes:

     variadic  Indicates whether the C function accepts a variable number of
	       arguments. The default value is “false”.

     sentinel  An integer value that specifies which argument (counting back‐
	       wards from the end of the argument list) must be a NULL value
	       to indicate the end of a variable length argument list (thus,
	       this is only legal for variadic functions).  (The
	       __attribute__((sentinel)) compiler attribute will be automati‐
	       cally recognized by the new parser, and the given sentinel
	       value (defaulting to zero), will be assigned to the sentinel
	       attribute.)

     inline    Indicates whether the C function is inline. In that case, the
	       symbol can be found in the respective .dylib file that comes
	       with the BridgeSupport file. Consult gen_bridge_metadata(1) to
	       know how the dylib files are generated. The default value is
	       “false”.

     Possible children: arg (zero or more), retval (zero or one).

   The function_alias element
     This element defines an alias or shortcut to a C function.

     Mandatory attributes:

     name      The name of the C function alias.

     original  The name of the original C function the alias points to.

   The class element
     This element defines an Objective-C class. Only classes where additional
     metadata is needed are described.

     Mandatory attributes:

     name  The name of the Objective-C class.

     Possible children: method (zero or more).

   The informal_protocol element
     This element defines an Objective-C informal protocol.

     Mandatory attributes:

     name  The name of the Objective-C informal protocol.

     Possible children: method (zero or more).

   The method element
     This element defines an Objective-C method. Only methods where additional
     metadata is needed are described.

     Mandatory attributes:

     selector  The selector of the Objective-C method.

     Mandatory attributes (only when declared under informal_protocol) :

     type, type64  The type of the Objective-C method, as a string of Objec‐
		   tive-C runtime encoding types. If the element has a differ‐
		   ent type on a 64-bit environment, the type64 attribute will
		   contain it. If the element does not exist on a 32-bit envi‐
		   ronment, only the type64 attribute will be used.

     Optional attributes:

     class_method  Whether this is a class method or not. The default value is
		   “false”.

     Optional attributes (only when not declared under informal_protocol) :

     variadic	 Indicates whether the method accepts a variable number of
		 arguments. The default value is “false”.

     sentinel	 An integer value that specifies which argument (counting
		 backwards from the end of the argument list) must be a NULL
		 value to indicate the end of a variable length argument list
		 (thus, this is only legal for variadic methods).  (The
		 __attribute__((sentinel)) compiler attribute will be automat‐
		 ically recognized by the new parser, and the given sentinel
		 value (defaulting to zero), will be assigned to the sentinel
		 attribute.)

     ignore	 Indicates whether the method should be ignored by the
		 bridges. The default value is “false”.

     suggestion	 If the ignore attribute is “true” , this attribute may con‐
		 tain a textual message that the bridges can deliver as an
		 exception or error message to be delivered to the user. By
		 default there is no suggestion.

     Possible children (only when not declared under informal_protocol) : arg
     (zero or more), retval (zero or one).

   The arg and retval elements
     These elements describe respectively an argument and a return value. They
     should be defined within both function and method elements, and their
     attributes depend under which element they are defined under.

     Optional attributes:

     c_array_length_in_arg	 Defines the argument or return value as a C
				 array whose length is defined by the value of
				 the given argument. The value of this
				 attribute is the index position of the argu‐
				 ment that should contain the array size. The
				 value can also be two integers separated by a
				 comma, which in that case means that the
				 first value is used when converting to C /
				 Objective-C, and the second when converting
				 back to the scripting language. This
				 attribute cannot be used with another
				 “c_array_” attribute.

     c_array_of_fixed_length	 Defines the argument or return value as a C
				 array of a fixed length. The value of this
				 attribute is the array size. This attribute
				 cannot be used with another “c_array_”
				 attribute.

     c_array_delimited_by_null	 Defines the argument or return value as a C
				 array that ends with a NULL value, if the
				 value of this attribute is “true”.  The
				 default value of this attribute is “false”.
				 This attribute cannot be used with another
				 “c_array_” attribute.

     c_array_of_variable_length	 Defines the argument or return value as a C
				 array of a variable length, if the value of
				 this attribute is “true”.  The default value
				 of this attribute is “false”.	This attribute
				 cannot be used with another “c_array_”
				 attribute.

     function_pointer		 Indicates whether the argument or return
				 value is a function or block pointer.	If
				 “true”, the type attribute will be '^?' for
				 functions and '@?' for blocks, and the cur‐
				 rent element should have a set of complete
				 arg and retval child elements to define both
				 the argument and the return value types of
				 the function or block pointer.

     sel_of_type, sel_of_type64	 This attribute, used for arguments or return
				 value of the type “SEL” (an Objective-C
				 selector), is used to provide the signature
				 of the method the selector should point to,
				 as a string of Objective-C runtime encoding
				 types.	 If the selector has a different type
				 on a 64-bit environment, the sel_of_type64
				 attribute will contain it. There is no
				 default value. This attribute can be used to
				 give a hint to the bridges when their default
				 behavior isn't sufficient.

     Optional attributes (arg only):

     c_array_length_in_retval  Defines the argument as a C like array whose
			       length is defined by the value of the return
			       value, if “true”.  The default value of this
			       attribute is “false”.  This attribute cannot be
			       used with another “c_array_” attribute.

     type_modifier	       The type modifier of the argument. Possible
			       values are “n” (in), “o” (out) and “N” (inout).
			       There is no default value.  (For Objective C
			       methods arguments, the in, out and inout type
			       modifiers will be automatically recognized by
			       the new parser, and the appropriate
			       type_modifier attribute will be set.)

     null_accepted	       Indicates whether a NULL value can be passed to
			       this argument. The default value is “true”.
			       (The __attribute__((nonnull)) compiler
			       attribute will be automatically recognized by
			       the new parser, and the corresponding argu‐
			       ment's null_accepted attribute will set to
			       “false”.)

     printf_format	       Indicates whether this argument accepts a
			       printf(3) format string value. The default
			       value is “false”.  (The
			       __attribute__((format(printf, m, n))) compiler
			       attribute will be automatically recognized by
			       the new parser, and the m-th argument's
			       printf_format attribute will be set to “true”.)

     Optional attributes (retval only):

     already_retained  A value of “true” indicates that the return value
		       should not be retained by the bridges. The default
		       value is “false”.

     Mandatory attributes (when declared under function):

     type, type64  The type of the argument or return value, as a string of
		   Objective-C runtime encoding types. If the element has a
		   different type on a 64-bit environment, the type64
		   attribute will contain it. If the element does not exist on
		   a 32-bit environment, only the type64 attribute will be
		   used.

     Mandatory attributes (when declared under method, arg only):

     index  The index position of the argument.

     Optional attributes (when declared under method):

     type, type64  The type of the argument or return value, as a string of
		   Objective-C runtime encoding types. If the element has a
		   different type on a 64-bit environment, the type64
		   attribute will contain it. If the element does not exist on
		   a 32-bit environment, only the type64 attribute will be
		   used. This attribute is optional for methods as the bridges
		   can retrieve the type by asking the runtime, but it is pos‐
		   sible to override the default type using this attribute.
		   There is no default value.

SEE ALSO
     gen_bridge_metadata(1) /System/Library/DTDs/BridgeSupport.dtd

BSD				 May 24, 2010				   BSD
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net