docs/reference/gobject/glib-genmarshal.xml

   1 <refentry id="glib-genmarshal" lang="en">
   2
   3 <refentryinfo>
   4   <title>glib-genmarshal</title>
   5   <productname>GObject</productname>
   6   <authorgroup>
   7     <author>
   8       <contrib>Developer</contrib>
   9       <firstname>Emmanuele</firstname>
  10       <surname>Bassi</surname>
  11     </author>
  12     <author>
  13       <contrib>Original developer</contrib>
  14       <firstname>Tim</firstname>
  15       <surname>Janik</surname>
  16     </author>
  17   </authorgroup>
  18 </refentryinfo>
  19
  20 <refmeta>
  21 <refentrytitle>glib-genmarshal</refentrytitle>
  22 <manvolnum>1</manvolnum>
  23 <refmiscinfo class="manual">User Commands</refmiscinfo>
  24 </refmeta>
  25
  26 <refnamediv>
  27 <refname>glib-genmarshal</refname>
  28 <refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
  29 </refnamediv>
  30
  31 <refsynopsisdiv>
  32 <cmdsynopsis>
  33 <command>glib-genmarshal</command>
  34 <arg choice="opt" rep="repeat">OPTION</arg>
  35 <arg choice="opt" rep="repeat">FILE</arg>
  36 </cmdsynopsis>
  37 </refsynopsisdiv>
  38
  39 <refsect1><title>Description</title>
  40 <para><command>glib-genmarshal</command> is a small utility that generates C code
  41 marshallers for callback functions of the GClosure mechanism in the GObject
  42 sublibrary of GLib. The marshaller functions have a standard signature,
  43 they get passed in the invoking closure, an array of value structures holding
  44 the callback function parameters and a value structure for the return value
  45 of the callback. The marshaller is then responsible to call the respective C
  46 code function of the closure with all the parameters on the stack and to
  47 collect its return value.
  48 </para>
  49
  50 <para><command>glib-genmarshal</command> takes a list of marshallers to generate as
  51 input. The marshaller list is either read from files passed as additional arguments
  52 on the command line; or from standard input, by using <literal>-</literal> as the
  53 input file.
  54 </para>
  55
  56 <refsect2><title>Marshaller list format</title>
  57 <para>
  58 The marshaller lists are processed line by line, a line can contain a
  59 comment in the form of
  60 <informalexample><programlisting>
  61 # this is a comment
  62 </programlisting></informalexample>
  63 or a marshaller specification of the form
  64 <programlisting>
  65 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
  66 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
  67 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
  68 </programlisting>
  69 </para>
  70 <para>
  71 The <replaceable>RTYPE</replaceable> part specifies the callback's return
  72 type and the <replaceable>PTYPE</replaceable>s right to the colon specify
  73 the callback's parameter list, except for the first and the last arguments
  74 which are always pointers.
  75 </para>
  76 </refsect2>
  77 <refsect2><title>Parameter types</title>
  78 <para>
  79 Currently, the following types are supported:
  80 <variablelist>
  81 <varlistentry>
  82 <term><replaceable>VOID</replaceable></term>
  83 <listitem><para>
  84 indicates no return type, or no extra parameters.
  85 If <replaceable>VOID</replaceable> is used as the parameter list, no
  86 additional parameters may be present.
  87 </para></listitem>
  88 </varlistentry>
  89
  90 <varlistentry>
  91 <term><replaceable>BOOLEAN</replaceable></term>
  92 <listitem><para>
  93 for boolean types (gboolean)
  94 </para></listitem>
  95 </varlistentry>
  96
  97 <varlistentry>
  98 <term><replaceable>CHAR</replaceable></term>
  99 <listitem><para>
 100 for signed char types (gchar)
 101 </para></listitem>
 102 </varlistentry>
 103
 104 <varlistentry>
 105 <term><replaceable>UCHAR</replaceable></term>
 106 <listitem><para>
 107 for unsigned char types (guchar)
 108 </para></listitem>
 109 </varlistentry>
 110
 111 <varlistentry>
 112 <term><replaceable>INT</replaceable></term>
 113 <listitem><para>
 114 for signed integer types (gint)
 115 </para></listitem>
 116 </varlistentry>
 117
 118 <varlistentry>
 119 <term><replaceable>UINT</replaceable></term>
 120 <listitem><para>
 121 for unsigned integer types (guint)
 122 </para></listitem>
 123 </varlistentry>
 124
 125 <varlistentry>
 126 <term><replaceable>LONG</replaceable></term>
 127 <listitem><para>
 128 for signed long integer types (glong)
 129 </para></listitem>
 130 </varlistentry>
 131
 132 <varlistentry>
 133 <term><replaceable>ULONG</replaceable></term>
 134 <listitem><para>
 135 for unsigned long integer types (gulong)
 136 </para></listitem>
 137 </varlistentry>
 138
 139 <varlistentry>
 140 <term><replaceable>INT64</replaceable></term>
 141 <listitem><para>
 142 for signed 64bit integer types (gint64)
 143 </para></listitem>
 144 </varlistentry>
 145
 146 <varlistentry>
 147 <term><replaceable>UINT64</replaceable></term>
 148 <listitem><para>
 149 for unsigned 64bit integer types (guint64)
 150 </para></listitem>
 151 </varlistentry>
 152
 153 <varlistentry>
 154 <term><replaceable>ENUM</replaceable></term>
 155 <listitem><para>
 156 for enumeration types (gint)
 157 </para></listitem>
 158 </varlistentry>
 159
 160 <varlistentry>
 161 <term><replaceable>FLAGS</replaceable></term>
 162 <listitem><para>
 163 for flag enumeration types (guint)
 164 </para></listitem>
 165 </varlistentry>
 166
 167 <varlistentry>
 168 <term><replaceable>FLOAT</replaceable></term>
 169 <listitem><para>
 170 for single-precision float types (gfloat)
 171 </para></listitem>
 172 </varlistentry>
 173
 174 <varlistentry>
 175 <term><replaceable>DOUBLE</replaceable></term>
 176 <listitem><para>
 177 for double-precision float types (gdouble)
 178 </para></listitem>
 179 </varlistentry>
 180
 181 <varlistentry>
 182 <term><replaceable>STRING</replaceable></term>
 183 <listitem><para>
 184 for string types (gchar*)
 185 </para></listitem>
 186 </varlistentry>
 187
 188 <varlistentry>
 189 <term><replaceable>BOXED</replaceable></term>
 190 <listitem><para>
 191 for boxed (anonymous but reference counted) types (GBoxed*)
 192 </para></listitem>
 193 </varlistentry>
 194
 195 <varlistentry>
 196 <term><replaceable>PARAM</replaceable></term>
 197 <listitem><para>
 198 for GParamSpec or derived types (GParamSpec*)
 199 </para></listitem>
 200 </varlistentry>
 201
 202 <varlistentry>
 203 <term><replaceable>POINTER</replaceable></term>
 204 <listitem><para>
 205 for anonymous pointer types (gpointer)
 206 </para></listitem>
 207 </varlistentry>
 208
 209 <varlistentry>
 210 <term><replaceable>OBJECT</replaceable></term>
 211 <listitem><para>
 212 for GObject or derived types (GObject*)
 213 </para></listitem>
 214 </varlistentry>
 215
 216 <varlistentry>
 217 <term><replaceable>VARIANT</replaceable></term>
 218 <listitem><para>
 219 for GVariant types (GVariant*)
 220 </para></listitem>
 221 </varlistentry>
 222
 223 <varlistentry>
 224 <term><replaceable>NONE</replaceable></term>
 225 <listitem><para>
 226 deprecated alias for <replaceable>VOID</replaceable>
 227 </para></listitem>
 228 </varlistentry>
 229
 230 <varlistentry>
 231 <term><replaceable>BOOL</replaceable></term>
 232 <listitem><para>
 233 deprecated alias for <replaceable>BOOLEAN</replaceable>
 234 </para></listitem>
 235 </varlistentry>
 236 </variablelist>
 237 </para>
 238 </refsect2>
 239 </refsect1>
 240
 241 <refsect1><title>Options</title>
 242 <variablelist>
 243
 244 <varlistentry>
 245 <term><option>--header</option></term>
 246 <listitem><para>
 247 Generate header file contents of the marshallers. This option is mutually
 248 exclusive with the <option>--body</option> option.
 249 </para></listitem>
 250 </varlistentry>
 251
 252 <varlistentry>
 253 <term><option>--body</option></term>
 254 <listitem><para>
 255 Generate C code file contents of the marshallers. This option is mutually
 256 exclusive with the <option>--header</option> option.
 257 </para></listitem>
 258 </varlistentry>
 259
 260 <varlistentry>
 261 <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
 262 <listitem><para>
 263 Specify marshaller prefix. The default prefix is <literal>`g_cclosure_user_marshal'</literal>.
 264 </para></listitem>
 265 </varlistentry>
 266
 267 <varlistentry>
 268 <term><option>--skip-source</option></term>
 269 <listitem><para>
 270 Skip source location remarks in generated comments.
 271 </para></listitem>
 272 </varlistentry>
 273
 274 <varlistentry>
 275 <term><option>--stdinc</option></term>
 276 <listitem><para>
 277 Use the standard marshallers of the GObject library, and include
 278 <filename>glib-object.h</filename> in generated header files. This
 279 option is mutually exclusive with the <option>--nostdinc</option>
 280 option.
 281 </para></listitem>
 282 </varlistentry>
 283
 284 <varlistentry>
 285 <term><option>--nostdinc</option></term>
 286 <listitem><para>
 287 Do not use the standard marshallers of the GObject library, and skip
 288 <filename>glib-object.h</filename> include directive in generated header files.
 289 This option is mutually exclusive with the <option>--stdinc</option> option.
 290 </para></listitem>
 291 </varlistentry>
 292
 293 <varlistentry>
 294 <term><option>--internal</option></term>
 295 <listitem><para>
 296 Mark generated functions as internal, using <literal>G_GNUC_INTERNAL</literal>.
 297 </para></listitem>
 298 </varlistentry>
 299
 300 <varlistentry>
 301 <term><option>--valist-marshallers</option></term>
 302 <listitem><para>
 303 Generate valist marshallers, for use with <function>g_signal_set_va_marshaller()</function>.
 304 </para></listitem>
 305 </varlistentry>
 306
 307 <varlistentry>
 308 <term><option>-v</option>, <option>--version</option></term>
 309 <listitem><para>
 310 Print version information.
 311 </para></listitem>
 312 </varlistentry>
 313
 314 <varlistentry>
 315 <term><option>--g-fatal-warnings</option></term>
 316 <listitem><para>
 317 Make warnings fatal, that is, exit immediately once a warning occurs.
 318 </para></listitem>
 319 </varlistentry>
 320
 321 <varlistentry>
 322 <term><option>-h</option>, <option>--help</option></term>
 323 <listitem><para>
 324 Print brief help and exit.
 325 </para></listitem>
 326 </varlistentry>
 327
 328 <varlistentry>
 329 <term><option>-v</option>, <option>--version</option></term>
 330 <listitem><para>
 331 Print version and exit.
 332 </para></listitem>
 333 </varlistentry>
 334
 335 <varlistentry>
 336 <term><option>--output=FILE</option></term>
 337 <listitem><para>
 338 Write output to <replaceable>FILE</replaceable> instead of the standard output.
 339 </para></listitem>
 340 </varlistentry>
 341
 342 <varlistentry>
 343 <term><option>--prototypes</option></term>
 344 <listitem><para>
 345 Generate function prototypes before the function definition in the C source
 346 file, in order to avoid a <literal>missing-prototypes</literal> compiler
 347 warning. This option is only useful when using the <option>--body</option>
 348 option.
 349 </para></listitem>
 350 </varlistentry>
 351
 352 <varlistentry>
 353 <term><option>--pragma-once</option></term>
 354 <listitem><para>
 355 Use the <literal>once</literal> pragma instead of an old style header guard
 356 when generating the C header file. This option is only useful when using the
 357 <option>--header</option> option.
 358 </para></listitem>
 359 </varlistentry>
 360
 361 <varlistentry>
 362 <term><option>--include-header=<replaceable>HEADER</replaceable></option></term>
 363 <listitem><para>
 364 Adds a <literal>#include</literal> directive for the given file in the C
 365 source file. This option is only useful when using the <option>--body</option>
 366 option.
 367 </para></listitem>
 368 </varlistentry>
 369
 370 <varlistentry>
 371 <term><option>-D <replaceable>SYMBOL[=VALUE]</replaceable></option></term>
 372 <listitem><para>
 373 Adds a <literal>#define</literal> C pre-processor directive for
 374 <replaceable>SYMBOL</replaceable> and its given <replaceable>VALUE</replaceable>,
 375 or "1" if the value is unset. You can use this option multiple times; if you do,
 376 all the symbols will be defined in the same order given on the command line, before
 377 the symbols undefined using the <option>-U</option> option. This option is only
 378 useful when using the <option>--body</option> option.
 379 </para></listitem>
 380 </varlistentry>
 381
 382 <varlistentry>
 383 <term><option>-U <replaceable>SYMBOL</replaceable></option></term>
 384 <listitem><para>
 385 Adds a <literal>#undef</literal> C pre-processor directive to undefine the
 386 given <replaceable>SYMBOL</replaceable>. You can use this option multiple times;
 387 if you do, all the symbols will be undefined in the same order given on the
 388 command line, after the symbols defined using the <option>-D</option> option.
 389 This option is only useful when using the <option>--body</option> option.
 390 </para></listitem>
 391 </varlistentry>
 392
 393 <varlistentry>
 394 <term><option>--quiet</option></term>
 395 <listitem><para>
 396 Minimizes the output of <command>glib-genmarshal</command>, by printing only
 397 warnings and errors. This option is mutually exclusive with the
 398 <option>--verbose</option> option.
 399 </para></listitem>
 400 </varlistentry>
 401
 402 <varlistentry>
 403 <term><option>--verbose</option></term>
 404 <listitem><para>
 405 Increases the verbosity of <command>glib-genmarshal</command>, by printing
 406 debugging information. This option is mutually exclusive with the
 407 <option>--quiet</option> option.
 408 </para></listitem>
 409 </varlistentry>
 410
 411 </variablelist>
 412 </refsect1>
 413
 414 <refsect1><title>Example</title>
 415 <para>
 416 To generate marshallers for the following callback functions:
 417 </para>
 418 <informalexample><programlisting>
 419 void   foo (gpointer data1,
 420             gpointer data2);
 421 void   bar (gpointer data1,
 422             gint     param1,
 423             gpointer data2);
 424 gfloat baz (gpointer data1,
 425             gboolean param1,
 426             guchar   param2,
 427             gpointer data2);
 428 </programlisting></informalexample>
 429 <para>
 430 The <filename>marshaller.list</filename> file has to look like this:
 431 </para>
 432 <programlisting>
 433 VOID:VOID
 434 VOID:INT
 435 FLOAT:BOOLEAN,UCHAR
 436 </programlisting>
 437 <para>
 438 and you call glib-genmarshal like this:
 439 </para>
 440 <programlisting>
 441 glib-genmarshal --header marshaller.list > marshaller.h
 442 glib-genmarshal --body marshaller.list > marshaller.c
 443 </programlisting>
 444 <para>
 445 The generated marshallers have the arguments encoded in their function name.
 446 For this particular list, they are
 447 </para>
 448 <programlisting>
 449 g_cclosure_user_marshal_VOID__VOID(...),
 450 g_cclosure_user_marshal_VOID__INT(...),
 451 g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
 452 </programlisting>
 453 <para>
 454 They can be used directly for GClosures or be passed in as the
 455 GSignalCMarshaller c_marshaller; argument upon creation of signals:
 456 </para>
 457 <informalexample><programlisting>
 458 GClosure *cc_foo, *cc_bar, *cc_baz;
 459
 460 cc_foo = g_cclosure_new (NULL, foo, NULL);
 461 g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
 462 cc_bar = g_cclosure_new (NULL, bar, NULL);
 463 g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
 464 cc_baz = g_cclosure_new (NULL, baz, NULL);
 465 g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
 466 </programlisting></informalexample>
 467 </refsect1>
 468 <refsect1><title>See also</title>
 469 <para>
 470 <citerefentry>
 471 <refentrytitle>glib-mkenums</refentrytitle>
 472 <manvolnum>1</manvolnum>
 473 </citerefentry>
 474 </para>
 475 </refsect1>
 476 </refentry>