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

'\" t
.\"     Title: glib-genmarshal
.\"    Author: Tim Janik
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 07/20/2016
.\"    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 standard input or from files passed as additional arguments on the command line\&.
.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
.\}
.sp
(up to 16
\fIPTYPE\fRs may be present)\&.
.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\&.
.RE
.PP
\fB\-\-body\fR
.RS 4
Generate C code file contents of the marshallers\&.
.RE
.PP
\fB\-\-prefix=\fR\fB\fIPREFIX\fR\fR
.RS 4
Specify marshaller prefix\&. The default prefix is
`g_cclosure_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
gmarshal\&.h
in generated header files\&.
.RE
.PP
\fB\-\-nostdinc\fR
.RS 4
Do not use the standard marshallers of the GObject library, and skip
gmarshal\&.h
include directive in generated header files\&.
.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 g_signal_set_va_marshaller()\&.
.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
.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)