| <refentry id="glib-genmarshal" lang="en"> |
| |
| <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">options</arg> |
| <arg choice="opt" rep="repeat">files</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> |
| </refsect1> |
| |
| <refsect1><title>Invocation</title> |
| <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>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=string</option>, <option>--prefix string</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>--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>--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> |
| </refsect2> |
| |
| <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 |
| <programlisting> |
| # this is a comment |
| </programlisting> |
| 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>Example</title> |
| <para> |
| To generate marshallers for the following callback functions: |
| </para> |
| <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> |
| <para> |
| The marshaller list has to look like this: |
| </para> |
| <programlisting> |
| VOID:VOID |
| VOID:INT |
| FLOAT:BOOLEAN,UCHAR |
| </programlisting> |
| <para> |
| The generated marshallers have the arguments encoded in their function name. |
| For this particular list, they are |
| </para> |
| <programlisting> |
| g_cclosure_marshal_VOID__VOID(), |
| g_cclosure_marshal_VOID__INT(), |
| g_cclosure_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> |
| <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); |
| </programlisting> |
| </refsect1> |
| <refsect1><title>See also</title> |
| <para> |
| <command>glib-mkenums</command>(1) |
| </para> |
| </refsect1> |
| <refsect1><title>Bugs</title> |
| <para> |
| None known yet. |
| </para> |
| </refsect1> |
| <refsect1><title>Author</title> |
| <para><command>glib-genmarshal</command> has been written by Tim Janik |
| <email>timj@gtk.org</email>. |
| </para> |
| <para> |
| This manual page was provided by Tim Janik <email>timj@gtk.org</email>. |
| </para> |
| </refsect1> |
| </refentry> |
| |
| |