nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 <refentry id="glib-genmarshal" lang="en">
2  
3 <refentryinfo>
4 <title>glib-genmarshal</title>
5 <productname>GObject</productname>
6 <authorgroup>
7 <author>
8 <contrib>Developer</contrib>
9 <firstname>Tim</firstname>
10 <surname>Janik</surname>
11 </author>
12 </authorgroup>
13 </refentryinfo>
14  
15 <refmeta>
16 <refentrytitle>glib-genmarshal</refentrytitle>
17 <manvolnum>1</manvolnum>
18 <refmiscinfo class="manual">User Commands</refmiscinfo>
19 </refmeta>
20  
21 <refnamediv>
22 <refname>glib-genmarshal</refname>
23 <refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
24 </refnamediv>
25  
26 <refsynopsisdiv>
27 <cmdsynopsis>
28 <command>glib-genmarshal</command>
29 <arg choice="opt" rep="repeat">OPTION</arg>
30 <arg choice="opt" rep="repeat">FILE</arg>
31 </cmdsynopsis>
32 </refsynopsisdiv>
33  
34 <refsect1><title>Description</title>
35 <para><command>glib-genmarshal</command> is a small utility that generates C code
36 marshallers for callback functions of the GClosure mechanism in the GObject
37 sublibrary of GLib. The marshaller functions have a standard signature,
38 they get passed in the invoking closure, an array of value structures holding
39 the callback function parameters and a value structure for the return value
40 of the callback. The marshaller is then responsible to call the respective C
41 code function of the closure with all the parameters on the stack and to
42 collect its return value.
43 </para>
44  
45 <para><command>glib-genmarshal</command> takes a list of marshallers to generate as
46 input. The marshaller list is either read from standard input or from files
47 passed as additional arguments on the command line.
48 </para>
49  
50 <refsect2><title>Marshaller list format</title>
51 <para>
52 The marshaller lists are processed line by line, a line can contain a
53 comment in the form of
54 <informalexample><programlisting>
55 # this is a comment
56 </programlisting></informalexample>
57 or a marshaller specification of the form
58 <programlisting>
59 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
60 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
61 <replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
62 </programlisting>
63 (up to 16 <replaceable>PTYPE</replaceable>s may be present).
64 </para>
65 <para>
66 The <replaceable>RTYPE</replaceable> part specifies the callback's return
67 type and the <replaceable>PTYPE</replaceable>s right to the colon specify
68 the callback's parameter list, except for the first and the last arguments
69 which are always pointers.
70 </para>
71 </refsect2>
72 <refsect2><title>Parameter types</title>
73 <para>
74 Currently, the following types are supported:
75 <variablelist>
76 <varlistentry>
77 <term><replaceable>VOID</replaceable></term>
78 <listitem><para>
79 indicates no return type, or no extra parameters.
80 If <replaceable>VOID</replaceable> is used as the parameter list, no
81 additional parameters may be present.
82 </para></listitem>
83 </varlistentry>
84  
85 <varlistentry>
86 <term><replaceable>BOOLEAN</replaceable></term>
87 <listitem><para>
88 for boolean types (gboolean)
89 </para></listitem>
90 </varlistentry>
91  
92 <varlistentry>
93 <term><replaceable>CHAR</replaceable></term>
94 <listitem><para>
95 for signed char types (gchar)
96 </para></listitem>
97 </varlistentry>
98  
99 <varlistentry>
100 <term><replaceable>UCHAR</replaceable></term>
101 <listitem><para>
102 for unsigned char types (guchar)
103 </para></listitem>
104 </varlistentry>
105  
106 <varlistentry>
107 <term><replaceable>INT</replaceable></term>
108 <listitem><para>
109 for signed integer types (gint)
110 </para></listitem>
111 </varlistentry>
112  
113 <varlistentry>
114 <term><replaceable>UINT</replaceable></term>
115 <listitem><para>
116 for unsigned integer types (guint)
117 </para></listitem>
118 </varlistentry>
119  
120 <varlistentry>
121 <term><replaceable>LONG</replaceable></term>
122 <listitem><para>
123 for signed long integer types (glong)
124 </para></listitem>
125 </varlistentry>
126  
127 <varlistentry>
128 <term><replaceable>ULONG</replaceable></term>
129 <listitem><para>
130 for unsigned long integer types (gulong)
131 </para></listitem>
132 </varlistentry>
133  
134 <varlistentry>
135 <term><replaceable>INT64</replaceable></term>
136 <listitem><para>
137 for signed 64bit integer types (gint64)
138 </para></listitem>
139 </varlistentry>
140  
141 <varlistentry>
142 <term><replaceable>UINT64</replaceable></term>
143 <listitem><para>
144 for unsigned 64bit integer types (guint64)
145 </para></listitem>
146 </varlistentry>
147  
148 <varlistentry>
149 <term><replaceable>ENUM</replaceable></term>
150 <listitem><para>
151 for enumeration types (gint)
152 </para></listitem>
153 </varlistentry>
154  
155 <varlistentry>
156 <term><replaceable>FLAGS</replaceable></term>
157 <listitem><para>
158 for flag enumeration types (guint)
159 </para></listitem>
160 </varlistentry>
161  
162 <varlistentry>
163 <term><replaceable>FLOAT</replaceable></term>
164 <listitem><para>
165 for single-precision float types (gfloat)
166 </para></listitem>
167 </varlistentry>
168  
169 <varlistentry>
170 <term><replaceable>DOUBLE</replaceable></term>
171 <listitem><para>
172 for double-precision float types (gdouble)
173 </para></listitem>
174 </varlistentry>
175  
176 <varlistentry>
177 <term><replaceable>STRING</replaceable></term>
178 <listitem><para>
179 for string types (gchar*)
180 </para></listitem>
181 </varlistentry>
182  
183 <varlistentry>
184 <term><replaceable>BOXED</replaceable></term>
185 <listitem><para>
186 for boxed (anonymous but reference counted) types (GBoxed*)
187 </para></listitem>
188 </varlistentry>
189  
190 <varlistentry>
191 <term><replaceable>PARAM</replaceable></term>
192 <listitem><para>
193 for GParamSpec or derived types (GParamSpec*)
194 </para></listitem>
195 </varlistentry>
196  
197 <varlistentry>
198 <term><replaceable>POINTER</replaceable></term>
199 <listitem><para>
200 for anonymous pointer types (gpointer)
201 </para></listitem>
202 </varlistentry>
203  
204 <varlistentry>
205 <term><replaceable>OBJECT</replaceable></term>
206 <listitem><para>
207 for GObject or derived types (GObject*)
208 </para></listitem>
209 </varlistentry>
210  
211 <varlistentry>
212 <term><replaceable>VARIANT</replaceable></term>
213 <listitem><para>
214 for GVariant types (GVariant*)
215 </para></listitem>
216 </varlistentry>
217  
218 <varlistentry>
219 <term><replaceable>NONE</replaceable></term>
220 <listitem><para>
221 deprecated alias for <replaceable>VOID</replaceable>
222 </para></listitem>
223 </varlistentry>
224  
225 <varlistentry>
226 <term><replaceable>BOOL</replaceable></term>
227 <listitem><para>
228 deprecated alias for <replaceable>BOOLEAN</replaceable>
229 </para></listitem>
230 </varlistentry>
231 </variablelist>
232 </para>
233 </refsect2>
234 </refsect1>
235  
236 <refsect1><title>Options</title>
237 <variablelist>
238  
239 <varlistentry>
240 <term><option>--header</option></term>
241 <listitem><para>
242 Generate header file contents of the marshallers.
243 </para></listitem>
244 </varlistentry>
245  
246 <varlistentry>
247 <term><option>--body</option></term>
248 <listitem><para>
249 Generate C code file contents of the marshallers.
250 </para></listitem>
251 </varlistentry>
252  
253 <varlistentry>
254 <term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
255 <listitem><para>
256 Specify marshaller prefix. The default prefix is <literal>`g_cclosure_marshal'</literal>.
257 </para></listitem>
258 </varlistentry>
259  
260 <varlistentry>
261 <term><option>--skip-source</option></term>
262 <listitem><para>
263 Skip source location remarks in generated comments.
264 </para></listitem>
265 </varlistentry>
266  
267 <varlistentry>
268 <term><option>--stdinc</option></term>
269 <listitem><para>
270 Use the standard marshallers of the GObject library, and include
271 <filename>gmarshal.h</filename> in generated header files.
272 </para></listitem>
273 </varlistentry>
274  
275 <varlistentry>
276 <term><option>--nostdinc</option></term>
277 <listitem><para>
278 Do not use the standard marshallers of the GObject library, and skip
279 <filename>gmarshal.h</filename> include directive in generated header files.
280 </para></listitem>
281 </varlistentry>
282  
283 <varlistentry>
284 <term><option>--internal</option></term>
285 <listitem><para>
286 Mark generated functions as internal, using G_GNUC_INTERNAL.
287 </para></listitem>
288 </varlistentry>
289  
290 <varlistentry>
291 <term><option>--valist-marshallers</option></term>
292 <listitem><para>
293 Generate valist marshallers, for use with g_signal_set_va_marshaller().
294 </para></listitem>
295 </varlistentry>
296  
297 <varlistentry>
298 <term><option>-v</option>, <option>--version</option></term>
299 <listitem><para>
300 Print version information.
301 </para></listitem>
302 </varlistentry>
303  
304 <varlistentry>
305 <term><option>--g-fatal-warnings</option></term>
306 <listitem><para>
307 Make warnings fatal, that is, exit immediately once a warning occurs.
308 </para></listitem>
309 </varlistentry>
310  
311 <varlistentry>
312 <term><option>-h</option>, <option>--help</option></term>
313 <listitem><para>
314 Print brief help and exit.
315 </para></listitem>
316 </varlistentry>
317  
318 <varlistentry>
319 <term><option>-v</option>, <option>--version</option></term>
320 <listitem><para>
321 Print version and exit.
322 </para></listitem>
323 </varlistentry>
324  
325 </variablelist>
326 </refsect1>
327  
328 <refsect1><title>Example</title>
329 <para>
330 To generate marshallers for the following callback functions:
331 </para>
332 <informalexample><programlisting>
333 void foo (gpointer data1,
334 gpointer data2);
335 void bar (gpointer data1,
336 gint param1,
337 gpointer data2);
338 gfloat baz (gpointer data1,
339 gboolean param1,
340 guchar param2,
341 gpointer data2);
342 </programlisting></informalexample>
343 <para>
344 The <filename>marshaller.list</filename> file has to look like this:
345 </para>
346 <programlisting>
347 VOID:VOID
348 VOID:INT
349 FLOAT:BOOLEAN,UCHAR
350 </programlisting>
351 <para>
352 and you call glib-genmarshal like this:
353 </para>
354 <programlisting>
355 glib-genmarshal --header marshaller.list > marshaller.h
356 glib-genmarshal --body marshaller.list > marshaller.c
357 </programlisting>
358 <para>
359 The generated marshallers have the arguments encoded in their function name.
360 For this particular list, they are
361 </para>
362 <programlisting>
363 g_cclosure_user_marshal_VOID__VOID(),
364 g_cclosure_user_marshal_VOID__INT(),
365 g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR().
366 </programlisting>
367 <para>
368 They can be used directly for GClosures or be passed in as the
369 GSignalCMarshaller c_marshaller; argument upon creation of signals:
370 </para>
371 <informalexample><programlisting>
372 GClosure *cc_foo, *cc_bar, *cc_baz;
373  
374 cc_foo = g_cclosure_new (NULL, foo, NULL);
375 g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
376 cc_bar = g_cclosure_new (NULL, bar, NULL);
377 g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
378 cc_baz = g_cclosure_new (NULL, baz, NULL);
379 g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
380 </programlisting></informalexample>
381 </refsect1>
382 <refsect1><title>See also</title>
383 <para>
384 <citerefentry>
385 <refentrytitle>glib-mkenums</refentrytitle>
386 <manvolnum>1</manvolnum>
387 </citerefentry>
388 </para>
389 </refsect1>
390 </refentry>