glib-genmarshal(1)

1GLIB-GENMARSHAL(1)               User Commands              GLIB-GENMARSHAL(1)
2
3
4

NAME

6       glib-genmarshal - C code marshaller generation utility for GLib
7       closures
8

SYNOPSIS

10       glib-genmarshal [OPTION...] [FILE...]
11

DESCRIPTION

13       glib-genmarshal is a small utility that generates C code marshallers
14       for callback functions of the GClosure mechanism in the GObject
15       sublibrary of GLib. The marshaller functions have a standard signature,
16       they get passed in the invoking closure, an array of value structures
17       holding the callback function parameters and a value structure for the
18       return value of the callback. The marshaller is then responsible to
19       call the respective C code function of the closure with all the
20       parameters on the stack and to collect its return value.
21
22       glib-genmarshal takes a list of marshallers to generate as input. The
23       marshaller list is either read from files passed as additional
24       arguments on the command line; or from standard input, by using - as
25       the input file.
26
27   Marshaller list format
28       The marshaller lists are processed line by line, a line can contain a
29       comment in the form of
30       or a marshaller specification of the form
31
32           RTYPE:PTYPE
33           RTYPE:PTYPE,PTYPE
34           RTYPE:PTYPE,PTYPE,PTYPE
35
36       The RTYPE part specifies the callback's return type and the PTYPEs
37       right to the colon specify the callback's parameter list, except for
38       the first and the last arguments which are always pointers.
39
40   Parameter types
41       Currently, the following types are supported:
42
43       VOID
44           indicates no return type, or no extra parameters. If VOID is used
45           as the parameter list, no additional parameters may be present.
46
47       BOOLEAN
48           for boolean types (gboolean)
49
50       CHAR
51           for signed char types (gchar)
52
53       UCHAR
54           for unsigned char types (guchar)
55
56       INT
57           for signed integer types (gint)
58
59       UINT
60           for unsigned integer types (guint)
61
62       LONG
63           for signed long integer types (glong)
64
65       ULONG
66           for unsigned long integer types (gulong)
67
68       INT64
69           for signed 64bit integer types (gint64)
70
71       UINT64
72           for unsigned 64bit integer types (guint64)
73
74       ENUM
75           for enumeration types (gint)
76
77       FLAGS
78           for flag enumeration types (guint)
79
80       FLOAT
81           for single-precision float types (gfloat)
82
83       DOUBLE
84           for double-precision float types (gdouble)
85
86       STRING
87           for string types (gchar*)
88
89       BOXED
90           for boxed (anonymous but reference counted) types (GBoxed*)
91
92       PARAM
93           for GParamSpec or derived types (GParamSpec*)
94
95       POINTER
96           for anonymous pointer types (gpointer)
97
98       OBJECT
99           for GObject or derived types (GObject*)
100
101       VARIANT
102           for GVariant types (GVariant*)
103
104       NONE
105           deprecated alias for VOID
106
107       BOOL
108           deprecated alias for BOOLEAN
109

OPTIONS

111       --header
112           Generate header file contents of the marshallers. This option is
113           mutually exclusive with the --body option.
114
115       --body
116           Generate C code file contents of the marshallers. This option is
117           mutually exclusive with the --header option.
118
119       --prefix=PREFIX
120           Specify marshaller prefix. The default prefix is
121           `g_cclosure_user_marshal'.
122
123       --skip-source
124           Skip source location remarks in generated comments.
125
126       --stdinc
127           Use the standard marshallers of the GObject library, and include
128           glib-object.h in generated header files. This option is mutually
129           exclusive with the --nostdinc option.
130
131       --nostdinc
132           Do not use the standard marshallers of the GObject library, and
133           skip glib-object.h include directive in generated header files.
134           This option is mutually exclusive with the --stdinc option.
135
136       --internal
137           Mark generated functions as internal, using G_GNUC_INTERNAL.
138
139       --valist-marshallers
140           Generate valist marshallers, for use with
141           g_signal_set_va_marshaller().
142
143       -v, --version
144           Print version information.
145
146       --g-fatal-warnings
147           Make warnings fatal, that is, exit immediately once a warning
148           occurs.
149
150       -h, --help
151           Print brief help and exit.
152
153       -v, --version
154           Print version and exit.
155
156       --output=FILE
157           Write output to FILE instead of the standard output.
158
159       --prototypes
160           Generate function prototypes before the function definition in the
161           C source file, in order to avoid a missing-prototypes compiler
162           warning. This option is only useful when using the --body option.
163
164       --pragma-once
165           Use the once pragma instead of an old style header guard when
166           generating the C header file. This option is only useful when using
167           the --header option.
168
169       --include-header=HEADER
170           Adds a #include directive for the given file in the C source file.
171           This option is only useful when using the --body option.
172
173       -D SYMBOL[=VALUE]
174           Adds a #define C pre-processor directive for SYMBOL and its given
175           VALUE, or "1" if the value is unset. You can use this option
176           multiple times; if you do, all the symbols will be defined in the
177           same order given on the command line, before the symbols undefined
178           using the -U option. This option is only useful when using the
179           --body option.
180
181       -U SYMBOL
182           Adds a #undef C pre-processor directive to undefine the given
183           SYMBOL. You can use this option multiple times; if you do, all the
184           symbols will be undefined in the same order given on the command
185           line, after the symbols defined using the -D option. This option is
186           only useful when using the --body option.
187
188       --quiet
189           Minimizes the output of glib-genmarshal, by printing only warnings
190           and errors. This option is mutually exclusive with the --verbose
191           option.
192
193       --verbose
194           Increases the verbosity of glib-genmarshal, by printing debugging
195           information. This option is mutually exclusive with the --quiet
196           option.
197

USING GLIB-GENMARSHAL WITH AUTOTOOLS

199       In order to use glib-genmarshal in your project when using Autotools as
200       the build system, you will first need to modify your configure.ac file
201       to ensure you find the appropriate command using pkg-config, similarly
202       as to how you discover the compiler and linker flags for GLib.
203
204           PKG_PROG_PKG_CONFIG([0.28])
205
206           PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
207
208       In your Makefile.am file you will typically need very simple rules to
209       generate the C files needed for the build.
210
211           marshal.h: marshal.list
212                   $(AM_V_GEN)$(GLIB_GENMARSHAL) \
213                           --header \
214                           --output=$@ \
215                           $<
216
217           marshal.c: marshal.list marshal.h
218                   $(AM_V_GEN)$(GLIB_GENMARSHAL) \
219                           --include-header=marshal.h \
220                           --body \
221                           --output=$@ \
222                           $<
223
224           BUILT_SOURCES += marshal.h marshal.c
225           CLEANFILES += marshal.h marshal.c
226           EXTRA_DIST += marshal.list
227
228       In the example above, the first rule generates the header file and
229       depends on a marshal.list file in order to regenerate the result in
230       case the marshallers list is updated. The second rule generates the
231       source file for the same marshal.list, and includes the file generated
232       by the header rule.
233

EXAMPLE

235       To generate marshallers for the following callback functions:
236
237           void   foo (gpointer data1,
238                       gpointer data2);
239           void   bar (gpointer data1,
240                       gint     param1,
241                       gpointer data2);
242           gfloat baz (gpointer data1,
243                       gboolean param1,
244                       guchar   param2,
245                       gpointer data2);
246
247       The marshaller.list file has to look like this:
248
249           VOID:VOID
250           VOID:INT
251           FLOAT:BOOLEAN,UCHAR
252
253       and you call glib-genmarshal like this:
254
255           glib-genmarshal --header marshaller.list > marshaller.h
256           glib-genmarshal --body marshaller.list > marshaller.c
257
258       The generated marshallers have the arguments encoded in their function
259       name. For this particular list, they are
260
261           g_cclosure_user_marshal_VOID__VOID(...),
262           g_cclosure_user_marshal_VOID__INT(...),
263           g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
264
265       They can be used directly for GClosures or be passed in as the
266       GSignalCMarshaller c_marshaller; argument upon creation of signals:
267
268           GClosure *cc_foo, *cc_bar, *cc_baz;
269
270           cc_foo = g_cclosure_new (NULL, foo, NULL);
271           g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
272           cc_bar = g_cclosure_new (NULL, bar, NULL);
273           g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
274           cc_baz = g_cclosure_new (NULL, baz, NULL);
275           g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
276

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

USING GLIB-GENMARSHAL WITH AUTOTOOLS

EXAMPLE

SEE ALSO