glib/docs/reference/gobject/glib-genmarshal.xml

<refentry id="glib-genmarshal" lang="en">

<refentryinfo>
  <title>glib-genmarshal</title>
  <productname>GObject</productname>
  <authorgroup>
    <author>
      <contrib>Developer</contrib>
      <firstname>Tim</firstname>
      <surname>Janik</surname>
    </author>
  </authorgroup>
</refentryinfo>

<refmeta>
<refentrytitle>glib-genmarshal</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>

<refnamediv>
<refname>glib-genmarshal</refname>
<refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>glib-genmarshal</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="opt" rep="repeat">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para><command>glib-genmarshal</command> 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.
</para>

<para><command>glib-genmarshal</command> 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.
</para>

<refsect2><title>Marshaller list format</title>
<para>
The marshaller lists are processed line by line, a line can contain a
comment in the form of
<informalexample><programlisting>
# this is a comment
</programlisting></informalexample>
or a marshaller specification of the form
<programlisting>
<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
</programlisting>
(up to 16 <replaceable>PTYPE</replaceable>s may be present).
</para>
<para>
The <replaceable>RTYPE</replaceable> part specifies the callback's return
type and the <replaceable>PTYPE</replaceable>s right to the colon specify
the callback's parameter list, except for the first and the last arguments
which are always pointers.
</para>
</refsect2>
<refsect2><title>Parameter types</title>
<para>
Currently, the following types are supported:
<variablelist>
<varlistentry>
<term><replaceable>VOID</replaceable></term>
<listitem><para>
indicates no return type, or no extra parameters.
If <replaceable>VOID</replaceable> is used as the parameter list, no
additional parameters may be present.
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>BOOLEAN</replaceable></term>
<listitem><para>
for boolean types (gboolean)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>CHAR</replaceable></term>
<listitem><para>
for signed char types (gchar)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>UCHAR</replaceable></term>
<listitem><para>
for unsigned char types (guchar)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>INT</replaceable></term>
<listitem><para>
for signed integer types (gint)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>UINT</replaceable></term>
<listitem><para>
for unsigned integer types (guint)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>LONG</replaceable></term>
<listitem><para>
for signed long integer types (glong)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>ULONG</replaceable></term>
<listitem><para>
for unsigned long integer types (gulong)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>INT64</replaceable></term>
<listitem><para>
for signed 64bit integer types (gint64)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>UINT64</replaceable></term>
<listitem><para>
for unsigned 64bit integer types (guint64)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>ENUM</replaceable></term>
<listitem><para>
for enumeration types (gint)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>FLAGS</replaceable></term>
<listitem><para>
for flag enumeration types (guint)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>FLOAT</replaceable></term>
<listitem><para>
for single-precision float types (gfloat)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>DOUBLE</replaceable></term>
<listitem><para>
for double-precision float types (gdouble)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>STRING</replaceable></term>
<listitem><para>
for string types (gchar*)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>BOXED</replaceable></term>
<listitem><para>
for boxed (anonymous but reference counted) types (GBoxed*)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>PARAM</replaceable></term>
<listitem><para>
for GParamSpec or derived types (GParamSpec*)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>POINTER</replaceable></term>
<listitem><para>
for anonymous pointer types (gpointer)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>OBJECT</replaceable></term>
<listitem><para>
for GObject or derived types (GObject*)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>VARIANT</replaceable></term>
<listitem><para>
for GVariant types (GVariant*)
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>NONE</replaceable></term>
<listitem><para>
deprecated alias for <replaceable>VOID</replaceable>
</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>BOOL</replaceable></term>
<listitem><para>
deprecated alias for <replaceable>BOOLEAN</replaceable>
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsect1>

<refsect1><title>Options</title>
<variablelist>

<varlistentry>
<term><option>--header</option></term>
<listitem><para>
Generate header file contents of the marshallers.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--body</option></term>
<listitem><para>
Generate C code file contents of the marshallers.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
<listitem><para>
Specify marshaller prefix. The default prefix is <literal>`g_cclosure_marshal'</literal>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--skip-source</option></term>
<listitem><para>
Skip source location remarks in generated comments.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--stdinc</option></term>
<listitem><para>
Use the standard marshallers of the GObject library, and include
<filename>gmarshal.h</filename> in generated header files.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--nostdinc</option></term>
<listitem><para>
Do not use the standard marshallers of the GObject library, and skip
<filename>gmarshal.h</filename> include directive in generated header files.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--internal</option></term>
<listitem><para>
Mark generated functions as internal, using G_GNUC_INTERNAL.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--valist-marshallers</option></term>
<listitem><para>
Generate valist marshallers, for use with g_signal_set_va_marshaller().
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
Print version information.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>--g-fatal-warnings</option></term>
<listitem><para>
Make warnings fatal, that is, exit immediately once a warning occurs.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print brief help and exit.
</para></listitem>
</varlistentry>

<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
Print version and exit.
</para></listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1><title>Example</title>
<para>
To generate marshallers for the following callback functions:
</para>
<informalexample><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);
</programlisting></informalexample>
<para>
The <filename>marshaller.list</filename> file has to look like this:
</para>
<programlisting>
VOID:VOID
VOID:INT
FLOAT:BOOLEAN,UCHAR
</programlisting>
<para>
and you call glib-genmarshal like this:
</para>
<programlisting>
glib-genmarshal --header marshaller.list > marshaller.h
glib-genmarshal --body marshaller.list > marshaller.c
</programlisting>
<para>
The generated marshallers have the arguments encoded in their function name.
For this particular list, they are
</para>
<programlisting>
g_cclosure_user_marshal_VOID__VOID(),
g_cclosure_user_marshal_VOID__INT(),
g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR().
</programlisting>
<para>
They can be used directly for GClosures or be passed in as the
GSignalCMarshaller c_marshaller; argument upon creation of signals:
</para>
<informalexample><programlisting>
GClosure *cc_foo, *cc_bar, *cc_baz;

cc_foo = g_cclosure_new (NULL, foo, NULL);
g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
cc_bar = g_cclosure_new (NULL, bar, NULL);
g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
cc_baz = g_cclosure_new (NULL, baz, NULL);
g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
</programlisting></informalexample>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>glib-mkenums</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>