glib-genmarshal

## glib-genmarshal glib-genmarshal — C code marshaller generation utility for GLib closures |

## Synopsis

`glib-genmarshal` [OPTION...] [FILE...]

## Description

glib-genmarshal 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.

glib-genmarshal 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.

### Marshaller list format

The marshaller lists are processed line by line, a line can contain a comment in the form of

    # this is a comment

or a marshaller specification of the form

    RTYPE:PTYPE
    RTYPE:PTYPE,PTYPE
    RTYPE:PTYPE,PTYPE,PTYPE

(up to 16 `PTYPE`s may be present).

The `RTYPE` part specifies the callback's return type and the `PTYPE`s right to the colon specify the callback's parameter list, except for the first and the last arguments which are always pointers.

### Parameter types

Currently, the following types are supported:

`VOID` | indicates no return type, or no extra parameters. If `VOID` is used as the parameter list, no additional parameters may be present.
`BOOLEAN` | for boolean types (gboolean)
`CHAR` | for signed char types (gchar)
`UCHAR` | for unsigned char types (guchar)
`INT` | for signed integer types (gint)
`UINT` | for unsigned integer types (guint)
`LONG` | for signed long integer types (glong)
`ULONG` | for unsigned long integer types (gulong)
`INT64` | for signed 64bit integer types (gint64)
`UINT64` | for unsigned 64bit integer types (guint64)
`ENUM` | for enumeration types (gint)
`FLAGS` | for flag enumeration types (guint)
`FLOAT` | for single-precision float types (gfloat)
`DOUBLE` | for double-precision float types (gdouble)
`STRING` | for string types (gchar*)
`BOXED` | for boxed (anonymous but reference counted) types (GBoxed*)
`PARAM` | for GParamSpec or derived types (GParamSpec*)
`POINTER` | for anonymous pointer types (gpointer)
`OBJECT` | for GObject or derived types (GObject*)
`VARIANT` | for GVariant types (GVariant*)
`NONE` | deprecated alias for `VOID`
`BOOL` | deprecated alias for `BOOLEAN`

## Options

`--header` | Generate header file contents of the marshallers.
`--body` | Generate C code file contents of the marshallers.
`--prefix=`PREFIX`` | Specify marshaller prefix. The default prefix is ``g_cclosure_marshal'`.
`--skip-source` | Skip source location remarks in generated comments.
`--stdinc` | Use the standard marshallers of the GObject library, and include `gmarshal.h` in generated header files.
`--nostdinc` | Do not use the standard marshallers of the GObject library, and skip `gmarshal.h` include directive in generated header files.
`--internal` | Mark generated functions as internal, using G_GNUC_INTERNAL.
`--valist-marshallers` | Generate valist marshallers, for use with g_signal_set_va_marshaller().
`-v`, `--version` | Print version information.
`--g-fatal-warnings` | Make warnings fatal, that is, exit immediately once a warning occurs.
`-h`, `--help` | Print brief help and exit.
`-v`, `--version` | Print version and exit.

## Example

To generate marshallers for the following callback functions:

    void   foo (gpointer data1,
                gpointer data2);
    void   bar (gpointer data1,
                gint     param1,
                gpointer data2);
    gfloat baz (gpointer data1,
                gboolean param1,
                guchar   param2,
                gpointer data2);

The `marshaller.list` file has to look like this:

    VOID:VOID
    VOID:INT
    FLOAT:BOOLEAN,UCHAR

and you call glib-genmarshal like this:

    glib-genmarshal --header marshaller.list > marshaller.h
    glib-genmarshal --body marshaller.list > marshaller.c

The generated marshallers have the arguments encoded in their function name. For this particular list, they are

    g_cclosure_user_marshal_VOID__VOID(),
    g_cclosure_user_marshal_VOID__INT(),
    g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR().

They can be used directly for GClosures or be passed in as the GSignalCMarshaller c_marshaller; argument upon creation of signals:

    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);

## See also

glib-mkenums(1)