'\" t
.\"     Title: glib-genmarshal
.\"    Author: Emmanuele Bassi
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/07/2018
.\"    Manual: User Commands
.\"    Source: GObject
.\"  Language: English
.\"
.TH "GLIB\-GENMARSHAL" "1" "" "GObject" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glib-genmarshal \- C code marshaller generation utility for GLib closures
.SH "SYNOPSIS"
.HP \w'\fBglib\-genmarshal\fR\ 'u
\fBglib\-genmarshal\fR [OPTION...] [FILE...]
.SH "DESCRIPTION"
.PP
\fBglib\-genmarshal\fR
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\&.
.PP
\fBglib\-genmarshal\fR
takes a list of marshallers to generate as input\&. The marshaller list is either read from files passed as additional arguments on the command line; or from standard input, by using
\-
as the input file\&.
.SS "Marshaller list format"
.PP
The marshaller lists are processed line by line, a line can contain a comment in the form of
.sp .if n \{\ .RS 4 .\} .nf # this is a comment .fi .if n \{\ .RE .\}
or a marshaller specification of the form
.sp
.if n \{\
.RS 4
.\}
.nf
\fIRTYPE\fR:\fIPTYPE\fR
\fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR
\fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR,\fIPTYPE\fR
.fi
.if n \{\
.RE
.\}
.PP
The
\fIRTYPE\fR
part specifies the callback\*(Aqs return type and the
\fIPTYPE\fRs right to the colon specify the callback\*(Aqs parameter list, except for the first and the last arguments which are always pointers\&.
.SS "Parameter types"
.PP
Currently, the following types are supported:
.PP
\fIVOID\fR
.RS 4
indicates no return type, or no extra parameters\&. If
\fIVOID\fR
is used as the parameter list, no additional parameters may be present\&.
.RE
.PP
\fIBOOLEAN\fR
.RS 4
for boolean types (gboolean)
.RE
.PP
\fICHAR\fR
.RS 4
for signed char types (gchar)
.RE
.PP
\fIUCHAR\fR
.RS 4
for unsigned char types (guchar)
.RE
.PP
\fIINT\fR
.RS 4
for signed integer types (gint)
.RE
.PP
\fIUINT\fR
.RS 4
for unsigned integer types (guint)
.RE
.PP
\fILONG\fR
.RS 4
for signed long integer types (glong)
.RE
.PP
\fIULONG\fR
.RS 4
for unsigned long integer types (gulong)
.RE
.PP
\fIINT64\fR
.RS 4
for signed 64bit integer types (gint64)
.RE
.PP
\fIUINT64\fR
.RS 4
for unsigned 64bit integer types (guint64)
.RE
.PP
\fIENUM\fR
.RS 4
for enumeration types (gint)
.RE
.PP
\fIFLAGS\fR
.RS 4
for flag enumeration types (guint)
.RE
.PP
\fIFLOAT\fR
.RS 4
for single\-precision float types (gfloat)
.RE
.PP
\fIDOUBLE\fR
.RS 4
for double\-precision float types (gdouble)
.RE
.PP
\fISTRING\fR
.RS 4
for string types (gchar*)
.RE
.PP
\fIBOXED\fR
.RS 4
for boxed (anonymous but reference counted) types (GBoxed*)
.RE
.PP
\fIPARAM\fR
.RS 4
for GParamSpec or derived types (GParamSpec*)
.RE
.PP
\fIPOINTER\fR
.RS 4
for anonymous pointer types (gpointer)
.RE
.PP
\fIOBJECT\fR
.RS 4
for GObject or derived types (GObject*)
.RE
.PP
\fIVARIANT\fR
.RS 4
for GVariant types (GVariant*)
.RE
.PP
\fINONE\fR
.RS 4
deprecated alias for
\fIVOID\fR
.RE
.PP
\fIBOOL\fR
.RS 4
deprecated alias for
\fIBOOLEAN\fR
.RE
.SH "OPTIONS"
.PP
\fB\-\-header\fR
.RS 4
Generate header file contents of the marshallers\&. This option is mutually exclusive with the
\fB\-\-body\fR
option\&.
.RE
.PP
\fB\-\-body\fR
.RS 4
Generate C code file contents of the marshallers\&. This option is mutually exclusive with the
\fB\-\-header\fR
option\&.
.RE
.PP
\fB\-\-prefix=\fR\fB\fIPREFIX\fR\fR
.RS 4
Specify marshaller prefix\&. The default prefix is
`g_cclosure_user_marshal\*(Aq\&.
.RE
.PP
\fB\-\-skip\-source\fR
.RS 4
Skip source location remarks in generated comments\&.
.RE
.PP
\fB\-\-stdinc\fR
.RS 4
Use the standard marshallers of the GObject library, and include
glib\-object\&.h
in generated header files\&. This option is mutually exclusive with the
\fB\-\-nostdinc\fR
option\&.
.RE
.PP
\fB\-\-nostdinc\fR
.RS 4
Do not use the standard marshallers of the GObject library, and skip
glib\-object\&.h
include directive in generated header files\&. This option is mutually exclusive with the
\fB\-\-stdinc\fR
option\&.
.RE
.PP
\fB\-\-internal\fR
.RS 4
Mark generated functions as internal, using
G_GNUC_INTERNAL\&.
.RE
.PP
\fB\-\-valist\-marshallers\fR
.RS 4
Generate valist marshallers, for use with
\fBg_signal_set_va_marshaller()\fR\&.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Print version information\&.
.RE
.PP
\fB\-\-g\-fatal\-warnings\fR
.RS 4
Make warnings fatal, that is, exit immediately once a warning occurs\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print brief help and exit\&.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Print version and exit\&.
.RE
.PP
\fB\-\-output=FILE\fR
.RS 4
Write output to
\fIFILE\fR
instead of the standard output\&.
.RE
.PP
\fB\-\-prototypes\fR
.RS 4
Generate function prototypes before the function definition in the C source file, in order to avoid a
missing\-prototypes
compiler warning\&. This option is only useful when using the
\fB\-\-body\fR
option\&.
.RE
.PP
\fB\-\-pragma\-once\fR
.RS 4
Use the
once
pragma instead of an old style header guard when generating the C header file\&. This option is only useful when using the
\fB\-\-header\fR
option\&.
.RE
.PP
\fB\-\-include\-header=\fR\fB\fIHEADER\fR\fR
.RS 4
Adds a
#include
directive for the given file in the C source file\&. This option is only useful when using the
\fB\-\-body\fR
option\&.
.RE
.PP
\fB\-D \fR\fB\fISYMBOL[=VALUE]\fR\fR
.RS 4
Adds a
#define
C pre\-processor directive for
\fISYMBOL\fR
and its given
\fIVALUE\fR, or "1" if the value is unset\&. You can use this option multiple times; if you do, all the symbols will be defined in the same order given on the command line, before the symbols undefined using the
\fB\-U\fR
option\&. This option is only useful when using the
\fB\-\-body\fR
option\&.
.RE
.PP
\fB\-U \fR\fB\fISYMBOL\fR\fR
.RS 4
Adds a
#undef
C pre\-processor directive to undefine the given
\fISYMBOL\fR\&. You can use this option multiple times; if you do, all the symbols will be undefined in the same order given on the command line, after the symbols defined using the
\fB\-D\fR
option\&. This option is only useful when using the
\fB\-\-body\fR
option\&.
.RE
.PP
\fB\-\-quiet\fR
.RS 4
Minimizes the output of
\fBglib\-genmarshal\fR, by printing only warnings and errors\&. This option is mutually exclusive with the
\fB\-\-verbose\fR
option\&.
.RE
.PP
\fB\-\-verbose\fR
.RS 4
Increases the verbosity of
\fBglib\-genmarshal\fR, by printing debugging information\&. This option is mutually exclusive with the
\fB\-\-quiet\fR
option\&.
.RE
.SH "USING GLIB\-GENMARSHAL WITH AUTOTOOLS"
.PP
In order to use
\fBglib\-genmarshal\fR
in your project when using Autotools as the build system, you will first need to modify your
configure\&.ac
file to ensure you find the appropriate command using
\fBpkg\-config\fR, similarly as to how you discover the compiler and linker flags for GLib\&.
.sp
.if n \{\
.RS 4
.\}
.nf
PKG_PROG_PKG_CONFIG([0\&.28])

PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib\-2\&.0], [glib_genmarshal])
.fi
.if n \{\
.RE
.\}
.PP
In your
Makefile\&.am
file you will typically need very simple rules to generate the C files needed for the build\&.
.sp
.if n \{\
.RS 4
.\}
.nf
marshal\&.h: marshal\&.list
        $(AM_V_GEN)$(GLIB_GENMARSHAL) \e
                \-\-header \e
                \-\-output=$@ \e
                $<

marshal\&.c: marshal\&.list marshal\&.h
        $(AM_V_GEN)$(GLIB_GENMARSHAL) \e
                \-\-include\-header=marshal\&.h \e
                \-\-body \e
                \-\-output=$@ \e
                $<

BUILT_SOURCES += marshal\&.h marshal\&.c
CLEANFILES += marshal\&.h marshal\&.c
EXTRA_DIST += marshal\&.list
.fi
.if n \{\
.RE
.\}
.PP
In the example above, the first rule generates the header file and depends on a
marshal\&.list
file in order to regenerate the result in case the marshallers list is updated\&. The second rule generates the source file for the same
marshal\&.list, and includes the file generated by the header rule\&.
.SH "EXAMPLE"
.PP
To generate marshallers for the following callback functions:
.sp
.if n \{\
.RS 4
.\}
.nf
void   foo (gpointer data1,
            gpointer data2);
void   bar (gpointer data1,
            gint     param1,
            gpointer data2);
gfloat baz (gpointer data1,
            gboolean param1,
            guchar   param2,
            gpointer data2);
.fi
.if n \{\
.RE
.\}
.PP
The
marshaller\&.list
file has to look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
VOID:VOID
VOID:INT
FLOAT:BOOLEAN,UCHAR
.fi
.if n \{\
.RE
.\}
.PP
and you call glib\-genmarshal like this:
.sp
.if n \{\
.RS 4
.\}
.nf
glib\-genmarshal \-\-header marshaller\&.list > marshaller\&.h
glib\-genmarshal \-\-body marshaller\&.list > marshaller\&.c
.fi
.if n \{\
.RE
.\}
.PP
The generated marshallers have the arguments encoded in their function name\&. For this particular list, they are
.sp
.if n \{\
.RS 4
.\}
.nf
g_cclosure_user_marshal_VOID__VOID(\&.\&.\&.),
g_cclosure_user_marshal_VOID__INT(\&.\&.\&.),
g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(\&.\&.\&.)\&.
.fi
.if n \{\
.RE
.\}
.PP
They can be used directly for GClosures or be passed in as the GSignalCMarshaller c_marshaller; argument upon creation of signals:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBglib-mkenums\fR(1)