docs/reference/gobject/glib-genmarshal.1

   1 '\" t
   2 .\"     Title: glib-genmarshal
   3 .\"    Author: [see the "Author" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
   5 .\"      Date: 04/19/2010
   6 .\"    Manual: User Commands
   7 .\"    Source: User Commands
   8 .\"  Language: English
   9 .\"
  10 .TH "GLIB\-GENMARSHAL" "1" "04/19/2010" "User Commands" "User Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 glib-genmarshal \- C code marshaller generation utility for GLib closures
  23 .SH "SYNOPSIS"
  24 .HP \w'\fBglib\-genmarshal\fR\ 'u
  25 \fBglib\-genmarshal\fR [options...] [files...]
  26 .SH "DESCRIPTION"
  27 .PP
  28 \fBglib\-genmarshal\fR
  29 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\&.
  30 .SH "INVOCATION"
  31 .PP
  32 \fBglib\-genmarshal\fR
  33 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\&.
  34 .SS "Options"
  35 .PP
  36 \fB\-\-header\fR
  37 .RS 4
  38 Generate header file contents of the marshallers\&.
  39 .RE
  40 .PP
  41 \fB\-\-body\fR
  42 .RS 4
  43 Generate C code file contents of the marshallers\&.
  44 .RE
  45 .PP
  46 \fB\-\-prefix=string\fR, \fB\-\-prefix string\fR
  47 .RS 4
  48 Specify marshaller prefix\&. The default prefix is
  49 `g_cclosure_marshal\'\&.
  50 .RE
  51 .PP
  52 \fB\-\-skip\-source\fR
  53 .RS 4
  54 Skip source location remarks in generated comments\&.
  55 .RE
  56 .PP
  57 \fB\-\-nostdinc\fR
  58 .RS 4
  59 Do not use the standard marshallers of the GObject library, and skip
  60 gmarshal\&.h
  61 include directive in generated header files\&.
  62 .RE
  63 .PP
  64 \fB\-\-g\-fatal\-warnings\fR
  65 .RS 4
  66 Make warnings fatal, that is, exit immediately once a warning occurs\&.
  67 .RE
  68 .PP
  69 \fB\-h\fR, \fB\-\-help\fR
  70 .RS 4
  71 Print brief help and exit\&.
  72 .RE
  73 .PP
  74 \fB\-v\fR, \fB\-\-version\fR
  75 .RS 4
  76 Print version and exit\&.
  77 .RE
  78 .SS "Marshaller list format"
  79 .PP
  80 The marshaller lists are processed line by line, a line can contain a comment in the form of
  81 .sp
  82 .if n \{\
  83 .RS 4
  84 .\}
  85 .nf
  86 # this is a comment
  87 .fi
  88 .if n \{\
  89 .RE
  90 .\}
  91 .sp
  92 or a marshaller specification of the form
  93 .sp
  94 .if n \{\
  95 .RS 4
  96 .\}
  97 .nf
  98 \fIRTYPE\fR:\fIPTYPE\fR
  99 \fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR
 100 \fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR,\fIPTYPE\fR
 101 .fi
 102 .if n \{\
 103 .RE
 104 .\}
 105 .sp
 106 (up to 16
 107 \fIPTYPE\fRs may be present)\&.
 108 .PP
 109 The
 110 \fIRTYPE\fR
 111 part specifies the callback\'s return type and the
 112 \fIPTYPE\fRs right to the colon specify the callback\'s parameter list, except for the first and the last arguments which are always pointers\&.
 113 .SS "Parameter types"
 114 .PP
 115 Currently, the following types are supported:
 116 .PP
 117 \fIVOID\fR
 118 .RS 4
 119 indicates no return type, or no extra parameters\&. If
 120 \fIVOID\fR
 121 is used as the parameter list, no additional parameters may be present\&.
 122 .RE
 123 .PP
 124 \fIBOOLEAN\fR
 125 .RS 4
 126 for boolean types (gboolean)
 127 .RE
 128 .PP
 129 \fICHAR\fR
 130 .RS 4
 131 for signed char types (gchar)
 132 .RE
 133 .PP
 134 \fIUCHAR\fR
 135 .RS 4
 136 for unsigned char types (guchar)
 137 .RE
 138 .PP
 139 \fIINT\fR
 140 .RS 4
 141 for signed integer types (gint)
 142 .RE
 143 .PP
 144 \fIUINT\fR
 145 .RS 4
 146 for unsigned integer types (guint)
 147 .RE
 148 .PP
 149 \fILONG\fR
 150 .RS 4
 151 for signed long integer types (glong)
 152 .RE
 153 .PP
 154 \fIULONG\fR
 155 .RS 4
 156 for unsigned long integer types (gulong)
 157 .RE
 158 .PP
 159 \fIINT64\fR
 160 .RS 4
 161 for signed 64bit integer types (gint64)
 162 .RE
 163 .PP
 164 \fIUINT64\fR
 165 .RS 4
 166 for unsigned 64bit integer types (guint64)
 167 .RE
 168 .PP
 169 \fIENUM\fR
 170 .RS 4
 171 for enumeration types (gint)
 172 .RE
 173 .PP
 174 \fIFLAGS\fR
 175 .RS 4
 176 for flag enumeration types (guint)
 177 .RE
 178 .PP
 179 \fIFLOAT\fR
 180 .RS 4
 181 for single\-precision float types (gfloat)
 182 .RE
 183 .PP
 184 \fIDOUBLE\fR
 185 .RS 4
 186 for double\-precision float types (gdouble)
 187 .RE
 188 .PP
 189 \fISTRING\fR
 190 .RS 4
 191 for string types (gchar*)
 192 .RE
 193 .PP
 194 \fIBOXED\fR
 195 .RS 4
 196 for boxed (anonymous but reference counted) types (GBoxed*)
 197 .RE
 198 .PP
 199 \fIPARAM\fR
 200 .RS 4
 201 for GParamSpec or derived types (GParamSpec*)
 202 .RE
 203 .PP
 204 \fIPOINTER\fR
 205 .RS 4
 206 for anonymous pointer types (gpointer)
 207 .RE
 208 .PP
 209 \fIOBJECT\fR
 210 .RS 4
 211 for GObject or derived types (GObject*)
 212 .RE
 213 .PP
 214 \fINONE\fR
 215 .RS 4
 216 deprecated alias for
 217 \fIVOID\fR
 218 .RE
 219 .PP
 220 \fIBOOL\fR
 221 .RS 4
 222 deprecated alias for
 223 \fIBOOLEAN\fR
 224 .RE
 225 .SH "EXAMPLE"
 226 .PP
 227 To generate marshallers for the following callback functions:
 228 .sp
 229 .if n \{\
 230 .RS 4
 231 .\}
 232 .nf
 233 void   foo (gpointer data1,
 234             gpointer data2);
 235 void   bar (gpointer data1,
 236             gint     param1,
 237             gpointer data2);
 238 gfloat baz (gpointer data1,
 239             gboolean param1,
 240             guchar   param2,
 241             gpointer data2);
 242 .fi
 243 .if n \{\
 244 .RE
 245 .\}
 246 .PP
 247 The marshaller list has to look like this:
 248 .sp
 249 .if n \{\
 250 .RS 4
 251 .\}
 252 .nf
 253 VOID:VOID
 254 VOID:INT
 255 FLOAT:BOOLEAN,UCHAR
 256 .fi
 257 .if n \{\
 258 .RE
 259 .\}
 260 .PP
 261 The generated marshallers have the arguments encoded in their function name\&. For this particular list, they are
 262 .sp
 263 .if n \{\
 264 .RS 4
 265 .\}
 266 .nf
 267 g_cclosure_marshal_VOID__VOID(),
 268 g_cclosure_marshal_VOID__INT(),
 269 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR()\&.
 270 .fi
 271 .if n \{\
 272 .RE
 273 .\}
 274 .PP
 275 They can be used directly for GClosures or be passed in as the GSignalCMarshaller c_marshaller; argument upon creation of signals:
 276 .sp
 277 .if n \{\
 278 .RS 4
 279 .\}
 280 .nf
 281 GClosure *cc_foo, *cc_bar, *cc_baz;
 282
 283 cc_foo = g_cclosure_new (NULL, foo, NULL);
 284 g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
 285 cc_bar = g_cclosure_new (NULL, bar, NULL);
 286 g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
 287 cc_baz = g_cclosure_new (NULL, baz, NULL);
 288 g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
 289 .fi
 290 .if n \{\
 291 .RE
 292 .\}
 293 .SH "SEE ALSO"
 294 .PP
 295
 296 \fBglib\-mkenums\fR(1)
 297 .SH "BUGS"
 298 .PP
 299 None known yet\&.
 300 .SH "AUTHOR"
 301 .PP
 302 \fBglib\-genmarshal\fR
 303 has been written by Tim Janik
 304 timj@gtk\&.org\&.
 305 .PP
 306 This manual page was provided by Tim Janik
 307 timj@gtk\&.org\&.