1 <refentry id="glib-genmarshal" lang="en">
4 <refentrytitle>glib-genmarshal</refentrytitle>
5 <manvolnum>1</manvolnum>
6 <refmiscinfo class="manual">User Commands</refmiscinfo>
10 <refname>glib-genmarshal</refname>
11 <refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
16 <command>glib-genmarshal</command>
17 <arg choice="opt" rep="repeat">options</arg>
18 <arg choice="opt" rep="repeat">files</arg>
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.
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.
40 <refsect2><title>Options</title>
44 <term><option>--header</option></term>
46 Generate header file contents of the marshallers.
51 <term><option>--body</option></term>
53 Generate C code file contents of the marshallers.
58 <term><option>--prefix=string</option>, <option>--prefix string</option></term>
60 Specify marshaller prefix. The default prefix is <literal>`g_cclosure_marshal'</literal>.
65 <term><option>--skip-source</option></term>
67 Skip source location remarks in generated comments.
72 <term><option>--nostdinc</option></term>
74 Do not use the standard marshallers of the GObject library, and skip
75 <filename>gmarshal.h</filename> include directive in generated header files.
80 <term><option>--internal</option></term>
82 Mark generated functions as internal, using G_GNUC_INTERNAL.
87 <term><option>--valist-marshallers</option></term>
89 Generate valist marshallers, for use with g_signal_set_va_marshaller().
94 <term><option>-v</option>, <option>--version</option></term>
96 Print version information.
101 <term><option>--g-fatal-warnings</option></term>
103 Make warnings fatal, that is, exit immediately once a warning occurs.
108 <term><option>-h</option>, <option>--help</option></term>
110 Print brief help and exit.
115 <term><option>-v</option>, <option>--version</option></term>
117 Print version and exit.
124 <refsect2><title>Marshaller list format</title>
126 The marshaller lists are processed line by line, a line can contain a
127 comment in the form of
131 or a marshaller specification of the form
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>
137 (up to 16 <replaceable>PTYPE</replaceable>s may be present).
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.
146 <refsect2><title>Parameter types</title>
148 Currently, the following types are supported:
151 <term><replaceable>VOID</replaceable></term>
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.
160 <term><replaceable>BOOLEAN</replaceable></term>
162 for boolean types (gboolean)
167 <term><replaceable>CHAR</replaceable></term>
169 for signed char types (gchar)
174 <term><replaceable>UCHAR</replaceable></term>
176 for unsigned char types (guchar)
181 <term><replaceable>INT</replaceable></term>
183 for signed integer types (gint)
188 <term><replaceable>UINT</replaceable></term>
190 for unsigned integer types (guint)
195 <term><replaceable>LONG</replaceable></term>
197 for signed long integer types (glong)
202 <term><replaceable>ULONG</replaceable></term>
204 for unsigned long integer types (gulong)
209 <term><replaceable>INT64</replaceable></term>
211 for signed 64bit integer types (gint64)
216 <term><replaceable>UINT64</replaceable></term>
218 for unsigned 64bit integer types (guint64)
223 <term><replaceable>ENUM</replaceable></term>
225 for enumeration types (gint)
230 <term><replaceable>FLAGS</replaceable></term>
232 for flag enumeration types (guint)
237 <term><replaceable>FLOAT</replaceable></term>
239 for single-precision float types (gfloat)
244 <term><replaceable>DOUBLE</replaceable></term>
246 for double-precision float types (gdouble)
251 <term><replaceable>STRING</replaceable></term>
253 for string types (gchar*)
258 <term><replaceable>BOXED</replaceable></term>
260 for boxed (anonymous but reference counted) types (GBoxed*)
265 <term><replaceable>PARAM</replaceable></term>
267 for GParamSpec or derived types (GParamSpec*)
272 <term><replaceable>POINTER</replaceable></term>
274 for anonymous pointer types (gpointer)
279 <term><replaceable>OBJECT</replaceable></term>
281 for GObject or derived types (GObject*)
286 <term><replaceable>VARIANT</replaceable></term>
288 for GVariant types (GVariant*)
293 <term><replaceable>NONE</replaceable></term>
295 deprecated alias for <replaceable>VOID</replaceable>
300 <term><replaceable>BOOL</replaceable></term>
302 deprecated alias for <replaceable>BOOLEAN</replaceable>
309 <refsect1><title>Example</title>
311 To generate marshallers for the following callback functions:
314 void foo (gpointer data1,
316 void bar (gpointer data1,
319 gfloat baz (gpointer data1,
325 The marshaller list has to look like this:
333 The generated marshallers have the arguments encoded in their function name.
334 For this particular list, they are
337 g_cclosure_marshal_VOID__VOID(),
338 g_cclosure_marshal_VOID__INT(),
339 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
342 They can be used directly for GClosures or be passed in as the
343 GSignalCMarshaller c_marshaller; argument upon creation of signals:
346 GClosure *cc_foo, *cc_bar, *cc_baz;
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);
356 <refsect1><title>See also</title>
358 <command>glib-mkenums</command>(1)
361 <refsect1><title>Bugs</title>
366 <refsect1><title>Author</title>
367 <para><command>glib-genmarshal</command> has been written by Tim Janik
368 <email>timj@gtk.org</email>.
371 This manual page was provided by Tim Janik <email>timj@gtk.org</email>.