gobject/glib-genmarshal.1

   1 .TH GLIB-GENMARSHAL 1 "18 Oct 2000"
   2 .SH NAME
   3 glib-genmarshal \- C code marshaller generation utility for GLib closures
   4 .SH SYNOPSIS
   5
   6 \fBglib-genmarshal\fP [\fIoptions\fP] [\fIfiles...\fP]
   7
   8 .SH DESCRIPTION
   9 \fBglib-genmarshal\fP is a small utility that generates C code marshallers
  10 for callback functions of the GClosure mechanism in the GObject sublibrary
  11 of GLib. The marshaller functions have a standard signature, they get passed
  12 in the invoking closure, an array of value structures holding the callback
  13 function parameters and a value structure for the return value of the
  14 callback. The marshaller is then responsible to call the respective C code
  15 function of the closure with all the parameters on the stack and to collect
  16 its return value.
  17
  18 .SH INVOCATION
  19
  20 \fBglib-genmarshal\fP takes a list of marshallers to generate as input.
  21 The marshaller list is either read from standard input or from files
  22 passed as additional arguments on the command line.
  23
  24 .SS Options
  25 .TP
  26 \fI--header
  27 Generate header file contents of the marshallers.
  28 .TP
  29 \fI--body
  30 Generate C code file contents of the marshallers.
  31 .TP
  32 \fI--prefix=string, --prefix string
  33 Specify marshaller prefix. The default prefix is `\fIg_cclosure_marshal\fP'.
  34 .TP
  35 \fI--skip-source
  36 Skip source location remarks in generated comments.
  37 .TP
  38 \fI--nostdinc
  39 Do not use the standard marshallers of the GObject library, and skip
  40 gmarshal.h include directive in generated header files.
  41 .TP
  42 \fI--internal
  43 Mark generated function as internal by using the G_GNUC_INTERNAL macro.
  44 .TP
  45 \fI--g-fatal-warnings
  46 Make warnings fatal, that is, exit immediately once a warning occurs.
  47 .TP
  48 \fI-h, --help\fP
  49 Print brief help and exit.
  50 .TP
  51 \fI-v, --version\fP
  52 Print version and exit.
  53 .PP
  54
  55 .SS Marshaller list format
  56 .PP
  57 The marshaller lists are processed line by line, a line can contain a
  58 comment in the form of
  59 .RS
  60 .PP
  61 # this is a comment
  62 .PP
  63 .RE
  64 or a marshaller specification of the form
  65 .RS
  66 .PP
  67 \fIRTYPE\fP:\fBPTYPE\fP
  68 .PP
  69 \fIRTYPE\fP:\fBPTYPE\fP,\fBPTYPE\fP
  70 .PP
  71 \fIRTYPE\fP:\fBPTYPE\fP,\fBPTYPE\fP,\fBPTYPE\fP
  72 .PP
  73 # up to 16 \fBPTYPE\fPs may be present
  74 .PP
  75 .RE
  76 The \fIRTYPE\fP part specifies the callback's return type and
  77 the \fBPTYPE\fPs right to the colon specify the callback's
  78 parameter list, except for the first and the last arguments which
  79 are always pointers.
  80 .PP
  81
  82 .SS Parameter types
  83 Currently, the following types are supported:
  84 .TP 12
  85 \fIVOID
  86 indicates no return type, or no extra parameters. if \fIVOID\fP is used as
  87 the parameter list, no additional parameters may be present.
  88 .TP 12
  89 \fIBOOLEAN
  90 for boolean types (gboolean)
  91 .TP 12
  92 \fICHAR
  93 for signed char types (gchar)
  94 .TP 12
  95 \fIUCHAR
  96 for unsigned char types (guchar)
  97 .TP 12
  98 \fIINT
  99 for signed integer types (gint)
 100 .TP 12
 101 \fIUINT
 102 for unsigned integer types (guint)
 103 .TP 12
 104 \fILONG
 105 for signed long integer types (glong)
 106 .TP 12
 107 \fIULONG
 108 for unsigned long integer types (gulong)
 109 .TP 12
 110 \fIINT64
 111 for signed 64bit integer types (gint64)
 112 .TP 12
 113 \fIUINT64
 114 for unsigned 64bit integer types (guint64)
 115 .TP 12
 116 \fIENUM
 117 for enumeration types (gint)
 118 .TP 12
 119 \fIFLAGS
 120 for flag enumeration types (guint)
 121 .TP 12
 122 \fIFLOAT
 123 for single-precision float types (gfloat)
 124 .TP 12
 125 \fIDOUBLE
 126 for double-precision float types (gdouble)
 127 .TP 12
 128 \fISTRING
 129 for string types (gchar*)
 130 .TP 12
 131 \fIBOXED
 132 for boxed (anonymous but reference counted) types (GBoxed*)
 133 .TP 12
 134 \fIPARAM
 135 for GParamSpec or derived types (GParamSpec*)
 136 .TP 12
 137 \fIPOINTER
 138 for anonymous pointer types (gpointer)
 139 .TP 12
 140 \fIOBJECT
 141 for GObject or derived types (GObject*)
 142 .TP 12
 143 \fINONE
 144 deprecated alias for \fIVOID\fP
 145 .TP 12
 146 \fIBOOL
 147 deprecated alias for \fIBOOLEAN\fP
 148
 149 .SH EXAMPLE
 150 To generate marshallers for the following callback functions:
 151 .PP
 152 .RS
 153 .nf
 154 void   foo (gpointer data1,
 155             gpointer data2);
 156 void   bar (gpointer data1,
 157             gint     param1,
 158             gpointer data2);
 159 gfloat baz (gpointer data1,
 160             gboolean param1,
 161             guchar   param2,
 162             gpointer data2);
 163 .fi
 164 .RE
 165 .PP
 166 The marshaller list has to look like this:
 167 .PP
 168 .RS
 169 .nf
 170 VOID:VOID
 171 VOID:INT
 172 FLOAT:BOOLEAN,UCHAR
 173 .fi
 174 .RE
 175 .PP
 176 The generated marshallers have the arguments encoded
 177 in their function name. For this particular list, they
 178 are
 179 g_cclosure_marshal_VOID__VOID(),
 180 g_cclosure_marshal_VOID__INT(),
 181 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
 182 .PP
 183 They can be used directly for GClosures or be passed in as
 184 the GSignalCMarshaller c_marshaller; argument upon creation
 185 of signals:
 186 .PP
 187 .nf
 188 GClosure *cc_foo, *cc_bar, *cc_baz;
 189
 190 cc_foo = g_cclosure_new (NULL, foo, NULL);
 191 g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
 192 cc_bar = g_cclosure_new (NULL, bar, NULL);
 193 g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
 194 cc_baz = g_cclosure_new (NULL, baz, NULL);
 195 g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
 196 .fi
 197 .PP
 198
 199
 200 .SH SEE ALSO
 201 \fB
 202 glib-mkenums(1)
 203 \fP
 204
 205 .SH BUGS
 206 None known yet.
 207
 208 .SH AUTHOR
 209 .B glib-genmarshal
 210 has been written by Tim Janik <timj@gtk.org>.
 211 .PP
 212 This manual page was provided by Tim Janik <timj@gtk.org>.