glib-genmarshal.1 revision 11153
8495845a800cf09321436aed996188c9a92cd647bnicholes<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
8495845a800cf09321436aed996188c9a92cd647bnicholes<!--ArborText, Inc., 1988-1999, v.4002-->
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg%booktitles;
8495845a800cf09321436aed996188c9a92cd647bnicholes<!ENTITY suncopy "Copyright (c) 2003,2006 Sun Microsystems, Inc. All Rights Reserved.">
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<!-- %Z%%M% %I% %E% SMI; -->
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<refmeta><refentrytitle>glib-genmarshal</refentrytitle><manvolnum>1</manvolnum>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<refmiscinfo class="copyright">&suncopy;</refmiscinfo>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<indexterm><primary>glib-genmarshal</primary></indexterm><indexterm><primary>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankggenerates C code marshallers for GLib closures</primary></indexterm><refnamediv
f43432d112920ab9af58aecc78d9fd5bacefc216fuankgid="glib-genmarshal-1-name"><refname>glib-genmarshal</refname><refpurpose>generates
f43432d112920ab9af58aecc78d9fd5bacefc216fuankgC code marshallers for GLib closures</refpurpose></refnamediv>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<refsynopsisdiv id="glib-genmarshal-1-synp"><title>&synp-tt;</title>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<arg choice="opt"><option>-g-fatal-warnings</option></arg>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<arg choice="opt"><option>-nostdinc</option> | <option>-stdinc</option></arg>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<arg choice="opt"><option>-prefix=<replaceable>dir</replaceable></option></arg>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<arg choice="opt" rep="repeat"><option role="nodash"><replaceable>file</replaceable></option></arg>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<refsect1 id="glib-genmarshal-1-desc"><title>&desc-tt;</title>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<para><command>&cmd;</command> generates C code marshallers for callback functions
5594e2aca1550d202df69bf273a876de2ccf01d4fuankgof the GClosure mechanism in the GObject sublibrary of GLib. The marshaller
8495845a800cf09321436aed996188c9a92cd647bnicholesfunctions have a standard signature. The following are passed to the marshaller
8495845a800cf09321436aed996188c9a92cd647bnicholesfunctions: the invoking closure, an array of value structures holding the
8495845a800cf09321436aed996188c9a92cd647bnicholescallback function parameters, and a value structure for the return value of
8495845a800cf09321436aed996188c9a92cd647bnicholesthe callback. The marshaller then calls the C code function of the closure
5594e2aca1550d202df69bf273a876de2ccf01d4fuankgwith all of the parameters on the stack, and collects the return value.</para>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<para><command>&cmd;</command> generates the specified list of marshallers.
f43432d112920ab9af58aecc78d9fd5bacefc216fuankgThe marshaller list is either read from standard input or from files passed
f43432d112920ab9af58aecc78d9fd5bacefc216fuankgas additional arguments on the command line.</para>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<refsect1 id="glib-genmarshal-1-exde"><title>&exde-tt;</title>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<para>The marshaller lists are processed line by line. A line can contain
8495845a800cf09321436aed996188c9a92cd647bnicholesa comment in the following format:</para>
44f575c8cb19a7a5cd61664a7848be6bc197df02fuankg<para>A marshaller list can contain a marshaller specification in the following
70953fb44a7140fe206c3a5f011e24209c8c5c6abnicholesformat:</para>
c5ef27ed1cf15c6b6345335c51416d2ea36198bfbnicholes<para><screen><replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
70953fb44a7140fe206c3a5f011e24209c8c5c6abnicholes<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>
8495845a800cf09321436aed996188c9a92cd647bnicholesPTYPE</replaceable>
8495845a800cf09321436aed996188c9a92cd647bnicholes<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>
8495845a800cf09321436aed996188c9a92cd647bnicholesPTYPE</replaceable>,<replaceable>PTYPE</replaceable>
8495845a800cf09321436aed996188c9a92cd647bnicholes# up to 16 <replaceable>PTYPE</replaceable>s may be present</screen></para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>RTYPE specifies the callback return type. PTYPE specifies the callback
8495845a800cf09321436aed996188c9a92cd647bnicholesparameter list, except for the first and the last arguments which are always
8495845a800cf09321436aed996188c9a92cd647bnicholespointers.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect2 id="glib-genmarshal-1-exde-ptyp"><title>Parameter Types</title>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>Currently, the following parameter types are supported:</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<variablelist><varlistentry><term><literal>BOOL</literal></term><listitem>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>Deprecated alias for <literal>BOOLEAN</literal>.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>BOOLEAN</literal></term><listitem><para>Boolean
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>BOXED</literal></term><listitem><para>Boxed,
8495845a800cf09321436aed996188c9a92cd647bnicholesanonymous but reference counted, type (<literal>GBoxed*</literal>).</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>CHAR</literal></term><listitem><para>Signed char
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>DOUBLE</literal></term><listitem><para>Double-precision
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>ENUM</literal></term><listitem><para>Enumeration
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>FLAGS</literal></term><listitem><para>Flag enumeration
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>FLOAT</literal></term><listitem><para>Single-precision
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>INT</literal></term><listitem><para>Signed integer
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>INT64</literal></term><listitem><para>Signed 64bit integer type (<literal>gint64</literal>).</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>LONG</literal></term><listitem><para>Signed long
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>NONE</literal></term><listitem><para>Deprecated
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>OBJECT</literal></term><listitem><para>GObject
8495845a800cf09321436aed996188c9a92cd647bnicholesor derived type (<literal>GObject*</literal>).</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>PARAM</literal></term><listitem><para>GParamSpec
8495845a800cf09321436aed996188c9a92cd647bnicholesor derived type (<literal>GParamSpec*</literal>).</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>POINTER</literal></term><listitem><para>Anonymous
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<varlistentry><term><literal>STRING</literal></term><listitem><para>String
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>UCHAR</literal></term><listitem><para>Unsigned
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>UINT</literal></term><listitem><para>Unsigned
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>UINT64</literal></term><listitem><para>Unsigned
8495845a800cf09321436aed996188c9a92cd647bnicholes64bit integer type (<literal>guint64</literal>).</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>ULONG</literal></term><listitem><para>Unsigned
8495845a800cf09321436aed996188c9a92cd647bnicholeslong integer type (<literal>gulong</literal>).</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><literal>VOID</literal></term><listitem><para>No return
8495845a800cf09321436aed996188c9a92cd647bnicholestype, or no extra parameters. If <literal>VOID</literal> is used as the parameter
8495845a800cf09321436aed996188c9a92cd647bnicholeslist, no additional parameters may be present.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect1 id="glib-genmarshal-1-opts"><title>&opts-tt;</title>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<variablelist termlength="medium"><varlistentry><term><option>-body</option></term>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<listitem><para>Generate the C code file contents of the marshallers.</para>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<varlistentry><term><option>-g-fatal-warnings<?Pub Caret></option></term>
8495845a800cf09321436aed996188c9a92cd647bnicholes<listitem><para>Make warnings fatal, that is, exit immediately once a warning
8495845a800cf09321436aed996188c9a92cd647bnicholesoccurs.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><option>-internal</option></term><listitem><para>Mark
8495845a800cf09321436aed996188c9a92cd647bnicholesgenerated functions as internal.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><option>-header</option></term><listitem><para>Generate
8495845a800cf09321436aed996188c9a92cd647bnicholesthe header file contents of the marshallers.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><option role="nodash">-h</option>, <option>-help</option></term><listitem><para>Show usage
8495845a800cf09321436aed996188c9a92cd647bnicholesand basic help information.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><option>-nostdinc</option></term><listitem><para>Do not
63e6fde94d80a39bd87f3893a5f9515fdbdb7aa4bnicholesuse the standard marshallers of the GObject library, and skip the <filename>
63e6fde94d80a39bd87f3893a5f9515fdbdb7aa4bnicholesgmarshal.h</filename> include directive in generated header files.</para>
63e6fde94d80a39bd87f3893a5f9515fdbdb7aa4bnicholes<varlistentry><term><option>-stdinc</option></term><listitem><para>Use
36b97bd7acc1ae60f6f31334b857617a083c4011bnicholesthe standard marshallers of the GObject library, and use the <filename>
36b97bd7acc1ae60f6f31334b857617a083c4011bnicholesgmarshal.h</filename> include directive in generated header files.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><option>-prefix=<replaceable>dir</replaceable></option></term>
8495845a800cf09321436aed996188c9a92cd647bnicholes<listitem><para>Specify the marshaller prefix. The default prefix is <literal>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<varlistentry><term><option>-skip-source</option></term><listitem><para>Skip
8495845a800cf09321436aed996188c9a92cd647bnicholessource location remarks in generated comments.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><option role="nodash">-v</option>, <option>-version</option></term><listitem><para>Show version
8495845a800cf09321436aed996188c9a92cd647bnicholesinformation.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect1 id="glib-genmarshal-1-oper"><title>&oper-tt;</title>
8495845a800cf09321436aed996188c9a92cd647bnicholes<variablelist termlength="medium"><varlistentry><term><option role="nodash"><replaceable>
8495845a800cf09321436aed996188c9a92cd647bnicholesfile</replaceable></option></term><listitem><para>Specifies the marshaller
0662ed52e814f8f08ef0e09956413a792584eddffuankgto be generated.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect1 id="glib-genmarshal-1-exam"><title>&exam-tt;</title>
8495845a800cf09321436aed996188c9a92cd647bnicholes<example role="example"><title>Generating Marshallers</title>
0662ed52e814f8f08ef0e09956413a792584eddffuankg<para>This example shows how to generate marshallers for the following callback
8495845a800cf09321436aed996188c9a92cd647bnicholesfunctions:</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes gpointer data2);
8495845a800cf09321436aed996188c9a92cd647bnicholesvoid bar (gpointer data1,
8495845a800cf09321436aed996188c9a92cd647bnicholes gint param1,
8495845a800cf09321436aed996188c9a92cd647bnicholes gpointer data2);
8495845a800cf09321436aed996188c9a92cd647bnicholesgfloat baz (gpointer data1,
8495845a800cf09321436aed996188c9a92cd647bnicholes gboolean param1,
8495845a800cf09321436aed996188c9a92cd647bnicholes guchar param2,
8495845a800cf09321436aed996188c9a92cd647bnicholes<screen>VOID:VOID
8495845a800cf09321436aed996188c9a92cd647bnicholesFLOAT:BOOLEAN,UCHAR</screen>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>The generated marshallers have the arguments encoded in their function
8495845a800cf09321436aed996188c9a92cd647bnicholesname. For this particular list, they are as follows:</para>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<screen>g_cclosure_marshal_VOID__VOID()
8495845a800cf09321436aed996188c9a92cd647bnicholesg_cclosure_marshal_VOID__INT()
8495845a800cf09321436aed996188c9a92cd647bnicholesg_cclosure_marshal_FLOAT__BOOLEAN_UCHAR()</screen>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>The generated marshallers can be used directly for GClosures or can
8495845a800cf09321436aed996188c9a92cd647bnicholesbe passed in as the GSignalCMarshaller c_marshaller; argument upon creation
8495845a800cf09321436aed996188c9a92cd647bnicholesof signals:</para>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<screen>GClosure *cc_foo, *cc_bar, *cc_baz;
8495845a800cf09321436aed996188c9a92cd647bnicholescc_foo = g_cclosure_new (NULL, foo, NULL);
8495845a800cf09321436aed996188c9a92cd647bnicholesg_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
8495845a800cf09321436aed996188c9a92cd647bnicholescc_bar = g_cclosure_new (NULL, bar, NULL);
8495845a800cf09321436aed996188c9a92cd647bnicholesg_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
8495845a800cf09321436aed996188c9a92cd647bnicholescc_baz = g_cclosure_new (NULL, baz, NULL);
8495845a800cf09321436aed996188c9a92cd647bnicholesg_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);</screen>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect1 id="glib-genmarshal-1-exit"><title>&exit-tt;</title>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>The following exit values are returned:</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<variablelist termlength="xtranarrow"><varlistentry><term><returnvalue>0</returnvalue></term>
8495845a800cf09321436aed996188c9a92cd647bnicholes<listitem><para>Application exited successfully</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><returnvalue>>0</returnvalue></term><listitem><para>Application
8495845a800cf09321436aed996188c9a92cd647bnicholesexited with failure</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect1 id="glib-genmarshal-1-file"><title>&file-tt;</title>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>The following files are used by this application:</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<variablelist termlength="wide"><varlistentry><term><filename>/usr/bin/&cmd;</filename>
cf7ca2f9eaa6523fefcccba4287b91637391fb51fuankg</term><listitem><para>The command-line executable for the application.</para>
8495845a800cf09321436aed996188c9a92cd647bnicholes<varlistentry><term><filename>/usr/share/gtk-doc/html/glib</filename></term><listitem>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<para>Location of developer documentation</para></listitem>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg</varlistentry>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<refsect1 id="glib-genmarshal-1-attr"><title>&attr-tt;</title>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankgfor descriptions of the following attributes:</para>
5594e2aca1550d202df69bf273a876de2ccf01d4fuankg<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">
8495845a800cf09321436aed996188c9a92cd647bnicholes<row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"
8495845a800cf09321436aed996188c9a92cd647bnicholes<row><entry><para>Availability</para></entry><entry><para>SUNWgnome-base-libs-devel
8495845a800cf09321436aed996188c9a92cd647bnicholes<row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry
f43432d112920ab9af58aecc78d9fd5bacefc216fuankgcolname="COLSPEC1"><para>Committed</para></entry></row>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg</informaltable>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<refsect1 id="glib-genmarshal-1-also"><title>&also-tt;</title>
f43432d112920ab9af58aecc78d9fd5bacefc216fuankg<!--Reference to another man page-->
8495845a800cf09321436aed996188c9a92cd647bnicholes<!--Reference to a Help manual-->
8495845a800cf09321436aed996188c9a92cd647bnicholes<!--Reference to a book.-->
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>gdk-pixbuf-csource</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>gdk-pixbuf-query-loaders</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>glib-gettextize</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>glib-mkenums</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>gobject-query</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>gtk-query-immodules-2.0</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>gtk-update-icon-cache</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8495845a800cf09321436aed996188c9a92cd647bnicholes<citerefentry><refentrytitle>libglib-2.0</refentrytitle><manvolnum>3</manvolnum></citerefentry>
8495845a800cf09321436aed996188c9a92cd647bnicholes<refsect1 id="glib-genmarshal-1-note"><title>¬e-tt;</title>
8495845a800cf09321436aed996188c9a92cd647bnicholes<para>Updated by Brian Cameron, Sun Microsystems Inc., 2003, 2006. Written by Tim
8495845a800cf09321436aed996188c9a92cd647bnicholesJanik.</para>