glib-genmarshal.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>glib-genmarshal</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="GObject Reference Manual"><link rel="up" href="rn02.html" title="Tools Reference"><link rel="previous" href="glib-mkenums.html" title="glib-mkenums"><link rel="next" href="gobject-query.html" title="gobject-query"><link rel="preface" href="pr01.html" title="Introduction"><link rel="reference" href="rn01.html" title="API Reference"><link rel="refentry" href="gobject-Type-Information.html" title="GType"><link rel="refentry" href="GTypePlugin.html" title="GTypePlugin"><link rel="refentry" href="GTypeModule.html" title="GTypeModule"><link rel="refentry" href="gobject-The-Base-Object-Type.html" title="GObject"><link rel="refentry" href="gobject-Enumeration-and-Flag-Types.html" title="Enums and Flags"><link rel="refentry" href="gobject-Boxed-Types.html" title="GBoxed"><link rel="refentry" href="gobject-Generic-values.html" title="Generic Values"><link rel="refentry" href="gobject-Standard-Parameter-and-Value-Types.html" title="Parameters and Values"><link rel="refentry" href="gobject-Varargs-Value-Collection.html" title="Varargs Value Collection"><link rel="refentry" href="gobject-GParamSpec.html" title="GParamSpec"><link rel="refentry" href="gobject-Signals.html" title="Signals"><link rel="refentry" href="gobject-Closures.html" title="Closures"><link rel="refentry" href="gobject-Value-arrays.html" title="Value arrays"><link rel="reference" href="rn02.html" title="Tools Reference"><link rel="refentry" href="glib-mkenums.html" title="glib-mkenums"><link rel="refentry" href="glib-genmarshal.html" title="glib-genmarshal"><link rel="refentry" href="gobject-query.html" title="gobject-query"><link rel="index" href="ix01.html" title="Index"><link rel="section" href="glib-genmarshal.html#id2920775" title="Description"><link rel="section" href="glib-genmarshal.html#id2920798" title="Invokation"><link rel="section" href="glib-genmarshal.html#id2921291" title="Example"><link rel="section" href="glib-genmarshal.html#id2921352" title="See also"><link rel="section" href="glib-genmarshal.html#id2921367" title="Bugs"><link rel="section" href="glib-genmarshal.html#id2921376" title="Author"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-mkenums.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="rn02.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GObject Reference Manual</th><td><a accesskey="n" href="gobject-query.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-genmarshal"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">glib-genmarshal</span></h2><p>glib-genmarshal — C code marshaller generation utility for GLib closures</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><tt class="command">glib-genmarshal</tt> [options...] [files...]</p></div></div><div class="refsect1" lang="en"><a name="id2920775"></a><h2>Description</h2><p>
<span><b class="command">glib-genmarshal</b></span> is a small utility that generates C code
marshallers for callback functions of the GClosure mechanism in the GObject
sublibrary of GLib. The marshaller functions have a standard signature,
they get passed in the invoking closure, an array of value structures holding
the callback function parameters and a value structure for the return value
of the callback. The marshaller is then responsible to call the respective C
code function of the closure with all the parameters on the stack and to
collect its return value.
</p></div><div class="refsect1" lang="en"><a name="id2920798"></a><h2>Invokation</h2><p>
<span><b class="command">glib-genmarshal</b></span> takes a list of marshallers to generate as
input. The marshaller list is either read from standard input or from files
passed as additional arguments on the command line.
</p><div class="refsect2" lang="en"><a name="id2920815"></a><h3>Options</h3><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><tt class="option">--header</tt></span></td><td><p>
Generate header file contents of the marshallers.
</p></td></tr><tr><td><span class="term"><tt class="option">--body</tt></span></td><td><p>
Generate C code file contents of the marshallers.
</p></td></tr><tr><td><span class="term"><tt class="option">--prefix=string</tt>, <tt class="option">--prefix string</tt></span></td><td><p>
Specify marshaller prefix. The default prefix is <tt class="literal">`g_cclosure_marshal'</tt>.
</p></td></tr><tr><td><span class="term"><tt class="option">--skip-source</tt></span></td><td><p>
Skip source location remarks in generated comments.
</p></td></tr><tr><td><span class="term"><tt class="option">--nostdinc</tt></span></td><td><p>
Do not use the standard marshallers of the GObject library, and skip
<tt class="filename">gmarshal.h</tt> include directive in generated header files.
</p></td></tr><tr><td><span class="term"><tt class="option">--g-fatal-warnings</tt></span></td><td><p>
Make warnings fatal, that is, exit immediately once a warning occurs.
</p></td></tr><tr><td><span class="term"><tt class="option">-h</tt>, <tt class="option">--help</tt></span></td><td><p>
Print brief help and exit.
</p></td></tr><tr><td><span class="term"><tt class="option">-v</tt>, <tt class="option">--version</tt></span></td><td><p>
Print version and exit.
</p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2920951"></a><h3>Marshaller list format</h3><p>
The marshaller lists are processed line by line, a line can contain a
comment in the form of
</p><pre class="programlisting">
# this is a comment
</pre><p>
or a marshaller specification of the form
</p><pre class="programlisting">
<i class="replaceable"><tt>RTYPE</tt></i>:<i class="replaceable"><tt>PTYPE</tt></i>
<i class="replaceable"><tt>RTYPE</tt></i>:<i class="replaceable"><tt>PTYPE</tt></i>,<i class="replaceable"><tt>PTYPE</tt></i>
<i class="replaceable"><tt>RTYPE</tt></i>:<i class="replaceable"><tt>PTYPE</tt></i>,<i class="replaceable"><tt>PTYPE</tt></i>,<i class="replaceable"><tt>PTYPE</tt></i>
</pre><p>
(up to 16 <i class="replaceable"><tt>PTYPE</tt></i>s may be present).
</p><p>
The <i class="replaceable"><tt>RTYPE</tt></i> part specifies the callback's return
type and the <i class="replaceable"><tt>PTYPE</tt></i>s right to the colon specify
the callback's parameter list, except for the first and the last arguments
which are always pointers.
</p></div><hr><div class="refsect2" lang="en"><a name="id2921023"></a><h3>Parameter types</h3><p>
Currently, the following types are supported:
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="replaceable"><tt>VOID</tt></i></span></td><td><p>
indicates no return type, or no extra parameters.
If <i class="replaceable"><tt>VOID</tt></i> is used as the parameter list, no
additional parameters may be present.
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>BOOLEAN</tt></i></span></td><td><p>
for boolean types (gboolean)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>CHAR</tt></i></span></td><td><p>
for signed char types (gchar)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>UCHAR</tt></i></span></td><td><p>
for unsigned char types (guchar)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>INT</tt></i></span></td><td><p>
for signed integer types (gint)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>UINT</tt></i></span></td><td><p>
for unsigned integer types (guint)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>LONG</tt></i></span></td><td><p>
for signed long integer types (glong)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>ULONG</tt></i></span></td><td><p>
for unsigned long integer types (gulong)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>ENUM</tt></i></span></td><td><p>
for enumeration types (gint)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>FLAGS</tt></i></span></td><td><p>
for flag enumeration types (guint)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>FLOAT</tt></i></span></td><td><p>
for single-precision float types (gfloat)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>DOUBLE</tt></i></span></td><td><p>
for double-precision float types (gdouble)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>STRING</tt></i></span></td><td><p>
for string types (gchar*)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>BOXED</tt></i></span></td><td><p>
for boxed (anonymous but reference counted) types (GBoxed*)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>PARAM</tt></i></span></td><td><p>
for GParamSpec or derived types (GParamSpec*)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>POINTER</tt></i></span></td><td><p>
for anonymous pointer types (gpointer)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>OBJECT</tt></i></span></td><td><p>
for GObject or derived types (GObject*)
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>NONE</tt></i></span></td><td><p>
deprecated alias for <i class="replaceable"><tt>VOID</tt></i>
</p></td></tr><tr><td><span class="term"><i class="replaceable"><tt>BOOL</tt></i></span></td><td><p>
deprecated alias for <i class="replaceable"><tt>BOOLEAN</tt></i>
</p></td></tr></tbody></table></div><p>
</p></div></div><div class="refsect1" lang="en"><a name="id2921291"></a><h2>Example</h2><p>
To generate marshallers for the following callback functions:
</p><pre class="programlisting">
void foo (gpointer data1,
gpointer data2);
void bar (gpointer data1,
gint param1,
gpointer data2);
gfloat baz (gpointer data1,
gboolean param1,
guchar param2,
gpointer data2);
</pre><p>
The marshaller list has to look like this:
</p><pre class="programlisting">
VOID:VOID
VOID:INT
FLOAT:BOOLEAN,UCHAR
</pre><p>
The generated marshallers have the arguments encoded in their function name.
For this particular list, they are
</p><pre class="programlisting">
g_cclosure_marshal_VOID__VOID(),
g_cclosure_marshal_VOID__INT(),
g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
</pre><p>
They can be used directly for GClosures or be passed in as the
GSignalCMarshaller c_marshaller; argument upon creation of signals:
</p><pre class="programlisting">
GClosure *cc_foo, *cc_bar, *cc_baz;
cc_foo = g_cclosure_new (NULL, foo, NULL);
g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
cc_bar = g_cclosure_new (NULL, bar, NULL);
g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
cc_baz = g_cclosure_new (NULL, baz, NULL);
g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
</pre></div><div class="refsect1" lang="en"><a name="id2921352"></a><h2>See also</h2><p>
<span><b class="command">glib-mkenums</b></span>(1)
</p></div><div class="refsect1" lang="en"><a name="id2921367"></a><h2>Bugs</h2><p>
None known yet.
</p></div><div class="refsect1" lang="en"><a name="id2921376"></a><h2>Author</h2><p>
<span><b class="command">glib-genmarshal</b></span> has been written by Tim Janik
<tt class="email"><<a href="mailto:timj@gtk.org">timj@gtk.org</a>></tt>.
</p><p>
This manual page was provided by Tim Janik <tt class="email"><<a href="mailto:timj@gtk.org">timj@gtk.org</a>></tt>.
</p></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="glib-mkenums.html"><b><< glib-mkenums</b></a></td><td align="right"><a accesskey="n" href="gobject-query.html"><b>gobject-query >></b></a></td></tr></table></body></html>