Blame docs/reference/gobject/html/glib-genmarshal.html

Packit ae235b
Packit ae235b
<html>
Packit ae235b
<head>
Packit ae235b
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
Packit ae235b
<title>glib-genmarshal: GObject Reference Manual</title>
Packit ae235b
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
Packit ae235b
<link rel="home" href="index.html" title="GObject Reference Manual">
Packit ae235b
<link rel="up" href="rn02.html" title="Tools Reference">
Packit ae235b
<link rel="prev" href="glib-mkenums.html" title="glib-mkenums">
Packit ae235b
<link rel="next" href="gobject-query.html" title="gobject-query">
Packit ae235b
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
Packit ae235b
<link rel="stylesheet" href="style.css" type="text/css">
Packit ae235b
</head>
Packit ae235b
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
Packit ae235b
Packit ae235b
Packit ae235b
Home
Packit ae235b
Up
Packit ae235b
Prev
Packit ae235b
Next
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

glib-genmarshal

Packit ae235b

glib-genmarshal — C code marshaller generation utility for GLib closures

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

Synopsis

Packit ae235b

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

Packit ae235b
Packit ae235b
Packit ae235b

Description

Packit ae235b

glib-genmarshal is a small utility that generates C code

Packit ae235b
marshallers for callback functions of the GClosure mechanism in the GObject
Packit ae235b
sublibrary of GLib. The marshaller functions have a standard signature,
Packit ae235b
they get passed in the invoking closure, an array of value structures holding
Packit ae235b
the callback function parameters and a value structure for the return value
Packit ae235b
of the callback. The marshaller is then responsible to call the respective C
Packit ae235b
code function of the closure with all the parameters on the stack and to
Packit ae235b
collect its return value.
Packit ae235b

Packit ae235b

glib-genmarshal takes a list of marshallers to generate as

Packit ae235b
input. The marshaller list is either read from files passed as additional arguments
Packit ae235b
on the command line; or from standard input, by using - as the
Packit ae235b
input file.
Packit ae235b

Packit ae235b
Packit ae235b

Marshaller list format

Packit ae235b

Packit ae235b
The marshaller lists are processed line by line, a line can contain a
Packit ae235b
comment in the form of
Packit ae235b

Packit ae235b
Packit ae235b
  
Packit ae235b
    
Packit ae235b
      
Packit ae235b
        
1
Packit ae235b
        
# this is a comment
Packit ae235b
      
Packit ae235b
    
Packit ae235b
  
Packit ae235b
Packit ae235b
Packit ae235b

Packit ae235b
or a marshaller specification of the form
Packit ae235b

Packit ae235b
Packit ae235b
RTYPE:PTYPE
Packit ae235b
RTYPE:PTYPE,PTYPE
Packit ae235b
RTYPE:PTYPE,PTYPE,PTYPE
Packit ae235b
Packit ae235b

Packit ae235b

Packit ae235b

Packit ae235b
The RTYPE part specifies the callback's return
Packit ae235b
type and the PTYPEs right to the colon specify
Packit ae235b
the callback's parameter list, except for the first and the last arguments
Packit ae235b
which are always pointers.
Packit ae235b

Packit ae235b
Packit ae235b

Packit ae235b
Packit ae235b

Parameter types

Packit ae235b

Packit ae235b
Currently, the following types are supported:
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

VOID

Packit ae235b

Packit ae235b
indicates no return type, or no extra parameters.
Packit ae235b
If VOID is used as the parameter list, no
Packit ae235b
additional parameters may be present.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

BOOLEAN

Packit ae235b

Packit ae235b
for boolean types (gboolean)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

CHAR

Packit ae235b

Packit ae235b
for signed char types (gchar)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

UCHAR

Packit ae235b

Packit ae235b
for unsigned char types (guchar)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

INT

Packit ae235b

Packit ae235b
for signed integer types (gint)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

UINT

Packit ae235b

Packit ae235b
for unsigned integer types (guint)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

LONG

Packit ae235b

Packit ae235b
for signed long integer types (glong)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

ULONG

Packit ae235b

Packit ae235b
for unsigned long integer types (gulong)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

INT64

Packit ae235b

Packit ae235b
for signed 64bit integer types (gint64)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

UINT64

Packit ae235b

Packit ae235b
for unsigned 64bit integer types (guint64)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

ENUM

Packit ae235b

Packit ae235b
for enumeration types (gint)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

FLAGS

Packit ae235b

Packit ae235b
for flag enumeration types (guint)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

FLOAT

Packit ae235b

Packit ae235b
for single-precision float types (gfloat)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

DOUBLE

Packit ae235b

Packit ae235b
for double-precision float types (gdouble)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

STRING

Packit ae235b

Packit ae235b
for string types (gchar*)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

BOXED

Packit ae235b

Packit ae235b
for boxed (anonymous but reference counted) types (GBoxed*)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

PARAM

Packit ae235b

Packit ae235b
for GParamSpec or derived types (GParamSpec*)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

POINTER

Packit ae235b

Packit ae235b
for anonymous pointer types (gpointer)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

OBJECT

Packit ae235b

Packit ae235b
for GObject or derived types (GObject*)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

VARIANT

Packit ae235b

Packit ae235b
for GVariant types (GVariant*)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

NONE

Packit ae235b

Packit ae235b
deprecated alias for VOID
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

BOOL

Packit ae235b

Packit ae235b
deprecated alias for BOOLEAN
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

Options

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

--header

Packit ae235b

Packit ae235b
Generate header file contents of the marshallers. This option is mutually
Packit ae235b
exclusive with the --body option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--body

Packit ae235b

Packit ae235b
Generate C code file contents of the marshallers. This option is mutually
Packit ae235b
exclusive with the --header option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--prefix=PREFIX

Packit ae235b

Packit ae235b
Specify marshaller prefix. The default prefix is `g_cclosure_user_marshal'.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--skip-source

Packit ae235b

Packit ae235b
Skip source location remarks in generated comments.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--stdinc

Packit ae235b

Packit ae235b
Use the standard marshallers of the GObject library, and include
Packit ae235b
glib-object.h in generated header files. This
Packit ae235b
option is mutually exclusive with the --nostdinc
Packit ae235b
option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--nostdinc

Packit ae235b

Packit ae235b
Do not use the standard marshallers of the GObject library, and skip
Packit ae235b
glib-object.h include directive in generated header files.
Packit ae235b
This option is mutually exclusive with the --stdinc option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--internal

Packit ae235b

Packit ae235b
Mark generated functions as internal, using G_GNUC_INTERNAL.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--valist-marshallers

Packit ae235b

Packit ae235b
Generate valist marshallers, for use with g_signal_set_va_marshaller().
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

-v, --version

Packit ae235b

Packit ae235b
Print version information.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--g-fatal-warnings

Packit ae235b

Packit ae235b
Make warnings fatal, that is, exit immediately once a warning occurs.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

-h, --help

Packit ae235b

Packit ae235b
Print brief help and exit.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

-v, --version

Packit ae235b

Packit ae235b
Print version and exit.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--output=FILE

Packit ae235b

Packit ae235b
Write output to FILE instead of the standard output.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--prototypes

Packit ae235b

Packit ae235b
Generate function prototypes before the function definition in the C source
Packit ae235b
file, in order to avoid a missing-prototypes compiler
Packit ae235b
warning. This option is only useful when using the --body
Packit ae235b
option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--pragma-once

Packit ae235b

Packit ae235b
Use the once pragma instead of an old style header guard
Packit ae235b
when generating the C header file. This option is only useful when using the
Packit ae235b
--header option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--include-header=HEADER

Packit ae235b

Packit ae235b
Adds a #include directive for the given file in the C
Packit ae235b
source file. This option is only useful when using the --body
Packit ae235b
option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

-D SYMBOL[=VALUE]

Packit ae235b

Packit ae235b
Adds a #define C pre-processor directive for
Packit ae235b
SYMBOL and its given VALUE,
Packit ae235b
or "1" if the value is unset. You can use this option multiple times; if you do,
Packit ae235b
all the symbols will be defined in the same order given on the command line, before
Packit ae235b
the symbols undefined using the -U option. This option is only
Packit ae235b
useful when using the --body option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

-U SYMBOL

Packit ae235b

Packit ae235b
Adds a #undef C pre-processor directive to undefine the
Packit ae235b
given SYMBOL. You can use this option multiple times;
Packit ae235b
if you do, all the symbols will be undefined in the same order given on the
Packit ae235b
command line, after the symbols defined using the -D option.
Packit ae235b
This option is only useful when using the --body option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--quiet

Packit ae235b

Packit ae235b
Minimizes the output of glib-genmarshal, by printing only
Packit ae235b
warnings and errors. This option is mutually exclusive with the
Packit ae235b
--verbose option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

--verbose

Packit ae235b

Packit ae235b
Increases the verbosity of glib-genmarshal, by printing
Packit ae235b
debugging information. This option is mutually exclusive with the
Packit ae235b
--quiet option.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

Using glib-genmarshal with Autotools

Packit ae235b

Packit ae235b
In order to use glib-genmarshal in your project when using
Packit ae235b
Autotools as the build system, you will first need to modify your
Packit ae235b
configure.ac file to ensure you find the appropriate
Packit ae235b
command using pkg-config, similarly as to how you discover
Packit ae235b
the compiler and linker flags for GLib.
Packit ae235b

Packit ae235b
Packit ae235b
  
Packit ae235b
    
Packit ae235b
      
Packit ae235b
        
1
Packit ae235b
2
Packit ae235b
3
Packit ae235b
        
PKG_PROG_PKG_CONFIG([0.28])
Packit ae235b
Packit ae235b
PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
Packit ae235b
      
Packit ae235b
    
Packit ae235b
  
Packit ae235b
Packit ae235b
Packit ae235b

Packit ae235b
In your Makefile.am file you will typically need very
Packit ae235b
simple rules to generate the C files needed for the build.
Packit ae235b

Packit ae235b
Packit ae235b
  
Packit ae235b
    
Packit ae235b
      
Packit ae235b
        
1
Packit ae235b
2
Packit ae235b
3
Packit ae235b
4
Packit ae235b
5
Packit ae235b
6
Packit ae235b
7
Packit ae235b
8
Packit ae235b
9
Packit ae235b
10
Packit ae235b
11
Packit ae235b
12
Packit ae235b
13
Packit ae235b
14
Packit ae235b
15
Packit ae235b
16
Packit ae235b
        
marshal.h: marshal.list
Packit ae235b
        $(AM_V_GEN)$(GLIB_GENMARSHAL) \
Packit ae235b
                --header \
Packit ae235b
                --output=$@ \
Packit ae235b
                $<
Packit ae235b
Packit ae235b
marshal.c: marshal.list marshal.h
Packit ae235b
        $(AM_V_GEN)$(GLIB_GENMARSHAL) \
Packit ae235b
                --include-header=marshal.h \
Packit ae235b
                --body \
Packit ae235b
                --output=$@ \
Packit ae235b
                $<
Packit ae235b
Packit ae235b
BUILT_SOURCES += marshal.h marshal.c
Packit ae235b
CLEANFILES += marshal.h marshal.c
Packit ae235b
EXTRA_DIST += marshal.list
Packit ae235b
      
Packit ae235b
    
Packit ae235b
  
Packit ae235b
Packit ae235b
Packit ae235b

Packit ae235b
In the example above, the first rule generates the header file and depends on
Packit ae235b
a marshal.list file in order to regenerate the result in
Packit ae235b
case the marshallers list is updated. The second rule generates the source file
Packit ae235b
for the same marshal.list, and includes the file generated
Packit ae235b
by the header rule.
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b

Example

Packit ae235b

Packit ae235b
To generate marshallers for the following callback functions:
Packit ae235b

Packit ae235b
Packit ae235b
  
Packit ae235b
    
Packit ae235b
      
Packit ae235b
        
1
Packit ae235b
2
Packit ae235b
3
Packit ae235b
4
Packit ae235b
5
Packit ae235b
6
Packit ae235b
7
Packit ae235b
8
Packit ae235b
9
Packit ae235b
        
void   foo (gpointer data1,
Packit ae235b
            gpointer data2);
Packit ae235b
void   bar (gpointer data1,
Packit ae235b
            gint     param1,
Packit ae235b
            gpointer data2);
Packit ae235b
gfloat baz (gpointer data1,
Packit ae235b
            gboolean param1,
Packit ae235b
            guchar   param2,
Packit ae235b
            gpointer data2);
Packit ae235b
      
Packit ae235b
    
Packit ae235b
  
Packit ae235b
Packit ae235b
Packit ae235b

Packit ae235b
The marshaller.list file has to look like this:
Packit ae235b

Packit ae235b
Packit ae235b
VOID:VOID
Packit ae235b
VOID:INT
Packit ae235b
FLOAT:BOOLEAN,UCHAR
Packit ae235b
Packit ae235b

Packit ae235b
and you call glib-genmarshal like this:
Packit ae235b

Packit ae235b
Packit ae235b
glib-genmarshal --header marshaller.list > marshaller.h
Packit ae235b
glib-genmarshal --body marshaller.list > marshaller.c
Packit ae235b
Packit ae235b

Packit ae235b
The generated marshallers have the arguments encoded in their function name.
Packit ae235b
For this particular list, they are
Packit ae235b

Packit ae235b
Packit ae235b
g_cclosure_user_marshal_VOID__VOID(...),
Packit ae235b
g_cclosure_user_marshal_VOID__INT(...),
Packit ae235b
g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
Packit ae235b
Packit ae235b

Packit ae235b
They can be used directly for GClosures or be passed in as the
Packit ae235b
GSignalCMarshaller c_marshaller; argument upon creation of signals:
Packit ae235b

Packit ae235b
Packit ae235b
  
Packit ae235b
    
Packit ae235b
      
Packit ae235b
        
1
Packit ae235b
2
Packit ae235b
3
Packit ae235b
4
Packit ae235b
5
Packit ae235b
6
Packit ae235b
7
Packit ae235b
8
Packit ae235b
        
GClosure *cc_foo, *cc_bar, *cc_baz;
Packit ae235b
Packit ae235b
cc_foo = g_cclosure_new (NULL, foo, NULL);
Packit ae235b
g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
Packit ae235b
cc_bar = g_cclosure_new (NULL, bar, NULL);
Packit ae235b
g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
Packit ae235b
cc_baz = g_cclosure_new (NULL, baz, NULL);
Packit ae235b
g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
Packit ae235b
      
Packit ae235b
    
Packit ae235b
  
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

See also

Packit ae235b

Packit ae235b
glib-mkenums(1)
Packit ae235b

Packit ae235b
Packit ae235b
Packit ae235b
Packit ae235b

Generated by GTK-Doc V1.27
Packit ae235b
</body>
Packit ae235b
</html>