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