Home | History | Annotate | Download | only in gobject 
      1 <refentry id="glib-genmarshal">
      2 
      3 <refmeta>
      4 <refentrytitle>glib-genmarshal</refentrytitle>
      5 <manvolnum>1</manvolnum>
      6 </refmeta>
      7 
      8 <refnamediv>
      9 <refname>glib-genmarshal</refname>
     10 <refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
     11 </refnamediv>
     12 
     13 <refsynopsisdiv>
     14 <cmdsynopsis>
     15 <command>glib-genmarshal</command>
     16 <arg choice="opt" rep="repeat">options</arg>
     17 <arg choice="opt" rep="repeat">files</arg>
     18 </cmdsynopsis>
     19 </refsynopsisdiv>
     20 
     21 <refsect1><title>Description</title>
     22 <para><command>glib-genmarshal</command> is a small utility that generates C code 
     23 marshallers for callback functions of the GClosure mechanism in the GObject 
     24 sublibrary of GLib. The marshaller functions have a standard signature, 
     25 they get passed in the invoking closure, an array of value structures holding
     26 the callback function parameters and a value structure for the return value 
     27 of the callback. The marshaller is then responsible to call the respective C 
     28 code function of the closure with all the parameters on the stack and to 
     29 collect its return value.
     30 </para>
     31 </refsect1>
     32 
     33 <refsect1><title>Invocation</title>
     34 <para><command>glib-genmarshal</command> takes a list of marshallers to generate as 
     35 input. The marshaller list is either read from standard input or from files
     36 passed as additional arguments on the command line.
     37 </para>
     38 
     39 <refsect2><title>Options</title>
     40 <variablelist>
     41 
     42 <varlistentry>
     43 <term><option>--header</option></term>
     44 <listitem><para>
     45 Generate header file contents of the marshallers.
     46 </para></listitem>
     47 </varlistentry>
     48 
     49 <varlistentry>
     50 <term><option>--body</option></term>
     51 <listitem><para>
     52 Generate C code file contents of the marshallers.
     53 </para></listitem>
     54 </varlistentry>
     55 
     56 <varlistentry>
     57 <term><option>--prefix=string</option>, <option>--prefix string</option></term>
     58 <listitem><para>
     59 Specify marshaller prefix. The default prefix is <literal>`g_cclosure_marshal'</literal>.
     60 </para></listitem>
     61 </varlistentry>
     62 
     63 <varlistentry>
     64 <term><option>--skip-source</option></term>
     65 <listitem><para>
     66 Skip source location remarks in generated comments.
     67 </para></listitem>
     68 </varlistentry>
     69 
     70 <varlistentry>
     71 <term><option>--nostdinc</option></term>
     72 <listitem><para>
     73 Do not use the standard marshallers of the GObject library, and skip 
     74 <filename>gmarshal.h</filename> include directive in generated header files.
     75 </para></listitem>
     76 </varlistentry>
     77 
     78 <varlistentry>
     79 <term><option>--g-fatal-warnings</option></term>
     80 <listitem><para>
     81 Make warnings fatal, that is, exit immediately once a warning occurs.
     82 </para></listitem>
     83 </varlistentry>
     84 
     85 <varlistentry>
     86 <term><option>-h</option>, <option>--help</option></term>
     87 <listitem><para>
     88 Print brief help and exit.
     89 </para></listitem>
     90 </varlistentry>
     91 
     92 <varlistentry>
     93 <term><option>-v</option>, <option>--version</option></term>
     94 <listitem><para>
     95 Print version and exit.
     96 </para></listitem>
     97 </varlistentry>
     98 
     99 </variablelist>
    100 </refsect2>
    101 
    102 <refsect2><title>Marshaller list format</title>
    103 <para>
    104 The marshaller lists are processed line by line, a line can contain a
    105 comment in the form of
    106 <programlisting>
    107 # this is a comment
    108 </programlisting>
    109 or a marshaller specification of the form
    110 <programlisting>
    111 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
    112 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
    113 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
    114 </programlisting>
    115 (up to 16 <replaceable>PTYPE</replaceable>s may be present).
    116 </para>
    117 <para>
    118 The <replaceable>RTYPE</replaceable> part specifies the callback's return 
    119 type and the <replaceable>PTYPE</replaceable>s right to the colon specify 
    120 the callback's parameter list, except for the first and the last arguments 
    121 which are always pointers.
    122 </para>
    123 </refsect2>
    124 <refsect2><title>Parameter types</title>
    125 <para>
    126 Currently, the following types are supported:
    127 <variablelist>
    128 <varlistentry>
    129 <term><replaceable>VOID</replaceable></term>
    130 <listitem><para>
    131 indicates no return type, or no extra parameters. 
    132 If <replaceable>VOID</replaceable> is used as the parameter list, no 
    133 additional parameters may be present.
    134 </para></listitem>
    135 </varlistentry>
    136 
    137 <varlistentry>
    138 <term><replaceable>BOOLEAN</replaceable></term>
    139 <listitem><para>
    140 for boolean types (gboolean)
    141 </para></listitem>
    142 </varlistentry>
    143 
    144 <varlistentry>
    145 <term><replaceable>CHAR</replaceable></term>
    146 <listitem><para>
    147 for signed char types (gchar)
    148 </para></listitem>
    149 </varlistentry>
    150 
    151 <varlistentry>
    152 <term><replaceable>UCHAR</replaceable></term>
    153 <listitem><para>
    154 for unsigned char types (guchar)
    155 </para></listitem>
    156 </varlistentry>
    157 
    158 <varlistentry>
    159 <term><replaceable>INT</replaceable></term>
    160 <listitem><para>
    161 for signed integer types (gint)
    162 </para></listitem>
    163 </varlistentry>
    164 
    165 <varlistentry>
    166 <term><replaceable>UINT</replaceable></term>
    167 <listitem><para>
    168 for unsigned integer types (guint)
    169 </para></listitem>
    170 </varlistentry>
    171 
    172 <varlistentry>
    173 <term><replaceable>LONG</replaceable></term>
    174 <listitem><para>
    175 for signed long integer types (glong)
    176 </para></listitem>
    177 </varlistentry>
    178 
    179 <varlistentry>
    180 <term><replaceable>ULONG</replaceable></term>
    181 <listitem><para>
    182 for unsigned long integer types (gulong)
    183 </para></listitem>
    184 </varlistentry>
    185 
    186 <varlistentry>
    187 <term><replaceable>INT64</replaceable></term>
    188 <listitem><para>
    189 for signed 64bit integer types (gint64)
    190 </para></listitem>
    191 </varlistentry>
    192 
    193 <varlistentry>
    194 <term><replaceable>UINT64</replaceable></term>
    195 <listitem><para>
    196 for unsigned 64bit integer types (guint64)
    197 </para></listitem>
    198 </varlistentry>
    199 
    200 <varlistentry>
    201 <term><replaceable>ENUM</replaceable></term>
    202 <listitem><para>
    203 for enumeration types (gint)
    204 </para></listitem>
    205 </varlistentry>
    206 
    207 <varlistentry>
    208 <term><replaceable>FLAGS</replaceable></term>
    209 <listitem><para>
    210 for flag enumeration types (guint)
    211 </para></listitem>
    212 </varlistentry>
    213 
    214 <varlistentry>
    215 <term><replaceable>FLOAT</replaceable></term>
    216 <listitem><para>
    217 for single-precision float types (gfloat)
    218 </para></listitem>
    219 </varlistentry>
    220 
    221 <varlistentry>
    222 <term><replaceable>DOUBLE</replaceable></term>
    223 <listitem><para>
    224 for double-precision float types (gdouble)
    225 </para></listitem>
    226 </varlistentry>
    227 
    228 <varlistentry>
    229 <term><replaceable>STRING</replaceable></term>
    230 <listitem><para>
    231 for string types (gchar*)
    232 </para></listitem>
    233 </varlistentry>
    234 
    235 <varlistentry>
    236 <term><replaceable>BOXED</replaceable></term>
    237 <listitem><para>
    238 for boxed (anonymous but reference counted) types (GBoxed*)
    239 </para></listitem>
    240 </varlistentry>
    241 
    242 <varlistentry>
    243 <term><replaceable>PARAM</replaceable></term>
    244 <listitem><para>
    245 for GParamSpec or derived types (GParamSpec*)
    246 </para></listitem>
    247 </varlistentry>
    248 
    249 <varlistentry>
    250 <term><replaceable>POINTER</replaceable></term>
    251 <listitem><para>
    252 for anonymous pointer types (gpointer)
    253 </para></listitem>
    254 </varlistentry>
    255 
    256 <varlistentry>
    257 <term><replaceable>OBJECT</replaceable></term>
    258 <listitem><para>
    259 for GObject or derived types (GObject*)
    260 </para></listitem>
    261 </varlistentry>
    262 
    263 <varlistentry>
    264 <term><replaceable>NONE</replaceable></term>
    265 <listitem><para>
    266 deprecated alias for <replaceable>VOID</replaceable>
    267 </para></listitem>
    268 </varlistentry>
    269 
    270 <varlistentry>
    271 <term><replaceable>BOOL</replaceable></term>
    272 <listitem><para>
    273 deprecated alias for <replaceable>BOOLEAN</replaceable>
    274 </para></listitem>
    275 </varlistentry>
    276 </variablelist>
    277 </para>
    278 </refsect2>
    279 </refsect1>
    280 <refsect1><title>Example</title>
    281 <para>
    282 To generate marshallers for the following callback functions:
    283 </para>
    284 <programlisting>
    285 void   foo (gpointer data1,
    286             gpointer data2);
    287 void   bar (gpointer data1,
    288             gint     param1,
    289             gpointer data2);
    290 gfloat baz (gpointer data1,
    291             gboolean param1,
    292             guchar   param2,
    293             gpointer data2);
    294 </programlisting>
    295 <para>
    296 The marshaller list has to look like this:
    297 </para>
    298 <programlisting>
    299 VOID:VOID
    300 VOID:INT
    301 FLOAT:BOOLEAN,UCHAR
    302 </programlisting>
    303 <para>
    304 The generated marshallers have the arguments encoded in their function name. 
    305 For this particular list, they are
    306 </para>
    307 <programlisting>
    308 g_cclosure_marshal_VOID__VOID(),
    309 g_cclosure_marshal_VOID__INT(), 
    310 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
    311 </programlisting>
    312 <para>
    313 They can be used directly for GClosures or be passed in as the 
    314 GSignalCMarshaller c_marshaller; argument upon creation of signals:
    315 </para>
    316 <programlisting>
    317 GClosure *cc_foo, *cc_bar, *cc_baz;
    318 
    319 cc_foo = g_cclosure_new (NULL, foo, NULL);
    320 g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
    321 cc_bar = g_cclosure_new (NULL, bar, NULL);
    322 g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
    323 cc_baz = g_cclosure_new (NULL, baz, NULL);
    324 g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
    325 </programlisting>
    326 </refsect1>
    327 <refsect1><title>See also</title>
    328 <para>
    329 <command>glib-mkenums</command>(1)
    330 </para>
    331 </refsect1>
    332 <refsect1><title>Bugs</title>
    333 <para>
    334 None known yet.
    335 </para>
    336 </refsect1>
    337 <refsect1><title>Author</title>
    338 <para><command>glib-genmarshal</command> has been written by Tim Janik 
    339 <email>timj (a] gtk.org</email>.
    340 </para>
    341 <para>
    342 This manual page was provided by Tim Janik <email>timj (a] gtk.org</email>.
    343 </para>
    344 </refsect1>
    345 </refentry>
    346 
    347 
    348