docs/reference/gobject/glib-genmarshal.1

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