docs/reference/gobject/glib-genmarshal.1

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