| .TH GLIB-GENMARSHAL 1 "18 Oct 2000" |
| .SH NAME |
| glib-genmarshal \- C code marshaller generation utility for GLib closures |
| .SH SYNOPSIS |
| |
| \fBglib-genmarshal\fP [\fIoptions\fP] [\fIfiles...\fP] |
| |
| .SH DESCRIPTION |
| \fBglib-genmarshal\fP 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. |
| |
| .SH INVOCATION |
| |
| \fBglib-genmarshal\fP 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 Options |
| .TP |
| \fI--header |
| Generate header file contents of the marshallers. |
| .TP |
| \fI--body |
| Generate C code file contents of the marshallers. |
| .TP |
| \fI--prefix=string, --prefix string |
| Specify marshaller prefix. The default prefix is `\fIg_cclosure_marshal\fP'. |
| .TP |
| \fI--skip-source |
| Skip source location remarks in generated comments. |
| .TP |
| \fI--nostdinc |
| Do not use the standard marshallers of the GObject library, and skip |
| gmarshal.h include directive in generated header files. |
| .TP |
| \fI--internal |
| Mark generated function as internal by using the G_GNUC_INTERNAL macro. |
| .TP |
| \fI--g-fatal-warnings |
| Make warnings fatal, that is, exit immediately once a warning occurs. |
| .TP |
| \fI-h, --help\fP |
| Print brief help and exit. |
| .TP |
| \fI-v, --version\fP |
| Print version and exit. |
| .PP |
| |
| .SS Marshaller list format |
| .PP |
| The marshaller lists are processed line by line, a line can contain a |
| comment in the form of |
| .RS |
| .PP |
| # this is a comment |
| .PP |
| .RE |
| or a marshaller specification of the form |
| .RS |
| .PP |
| \fIRTYPE\fP:\fBPTYPE\fP |
| .PP |
| \fIRTYPE\fP:\fBPTYPE\fP,\fBPTYPE\fP |
| .PP |
| \fIRTYPE\fP:\fBPTYPE\fP,\fBPTYPE\fP,\fBPTYPE\fP |
| .PP |
| # up to 16 \fBPTYPE\fPs may be present |
| .PP |
| .RE |
| The \fIRTYPE\fP part specifies the callback's return type and |
| the \fBPTYPE\fPs right to the colon specify the callback's |
| parameter list, except for the first and the last arguments which |
| are always pointers. |
| .PP |
| |
| .SS Parameter types |
| Currently, the following types are supported: |
| .TP 12 |
| \fIVOID |
| indicates no return type, or no extra parameters. if \fIVOID\fP is used as |
| the parameter list, no additional parameters may be present. |
| .TP 12 |
| \fIBOOLEAN |
| for boolean types (gboolean) |
| .TP 12 |
| \fICHAR |
| for signed char types (gchar) |
| .TP 12 |
| \fIUCHAR |
| for unsigned char types (guchar) |
| .TP 12 |
| \fIINT |
| for signed integer types (gint) |
| .TP 12 |
| \fIUINT |
| for unsigned integer types (guint) |
| .TP 12 |
| \fILONG |
| for signed long integer types (glong) |
| .TP 12 |
| \fIULONG |
| for unsigned long integer types (gulong) |
| .TP 12 |
| \fIINT64 |
| for signed 64bit integer types (gint64) |
| .TP 12 |
| \fIUINT64 |
| for unsigned 64bit integer types (guint64) |
| .TP 12 |
| \fIENUM |
| for enumeration types (gint) |
| .TP 12 |
| \fIFLAGS |
| for flag enumeration types (guint) |
| .TP 12 |
| \fIFLOAT |
| for single-precision float types (gfloat) |
| .TP 12 |
| \fIDOUBLE |
| for double-precision float types (gdouble) |
| .TP 12 |
| \fISTRING |
| for string types (gchar*) |
| .TP 12 |
| \fIBOXED |
| for boxed (anonymous but reference counted) types (GBoxed*) |
| .TP 12 |
| \fIPARAM |
| for GParamSpec or derived types (GParamSpec*) |
| .TP 12 |
| \fIPOINTER |
| for anonymous pointer types (gpointer) |
| .TP 12 |
| \fIOBJECT |
| for GObject or derived types (GObject*) |
| .TP 12 |
| \fINONE |
| deprecated alias for \fIVOID\fP |
| .TP 12 |
| \fIBOOL |
| deprecated alias for \fIBOOLEAN\fP |
| |
| .SH EXAMPLE |
| To generate marshallers for the following callback functions: |
| .PP |
| .RS |
| .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 |
| .RE |
| .PP |
| The marshaller list has to look like this: |
| .PP |
| .RS |
| .nf |
| VOID:VOID |
| VOID:INT |
| FLOAT:BOOLEAN,UCHAR |
| .fi |
| .RE |
| .PP |
| The generated marshallers have the arguments encoded |
| in their function name. For this particular list, they |
| are |
| g_cclosure_marshal_VOID__VOID(), |
| g_cclosure_marshal_VOID__INT(), |
| g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR(). |
| .PP |
| They can be used directly for GClosures or be passed in as |
| the GSignalCMarshaller c_marshaller; argument upon creation |
| of signals: |
| .PP |
| .nf |
| 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); |
| .fi |
| .PP |
| |
| |
| .SH SEE ALSO |
| \fB |
| glib-mkenums(1) |
| \fP |
| |
| .SH BUGS |
| None known yet. |
| |
| .SH AUTHOR |
| .B glib-genmarshal |
| has been written by Tim Janik <timj@gtk.org>. |
| .PP |
| This manual page was provided by Tim Janik <timj@gtk.org>. |
