docs/reference/gobject/glib-genmarshal.xml

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