docs/reference/gobject/glib-genmarshal.xml

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