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--g-fatal-warnings
  39 Make warnings fatal, that is, exit immediately once a warning occours.
  40 .TP
  41 \fI-h, --help\fP
  42 Print brief help and exit.
  43 .TP
  44 \fI-v, --version\fP
  45 Print version and exit.
  46 .PP
  47
  48 .SS Marshaller list format
  49 .PP
  50 The marshaller lists are processed line by line, a line can contain a
  51 comment in the form of
  52 .RS
  53 .PP
  54 # this is a comment
  55 .PP
  56 .RE
  57 or a marshaller specification of the form
  58 .RS
  59 .PP
  60 \fIRTYPE\fP:\fBPTYPE\fP
  61 .PP
  62 \fIRTYPE\fP:\fBPTYPE\fP,\fBPTYPE\fP
  63 .PP
  64 \fIRTYPE\fP:\fBPTYPE\fP,\fBPTYPE\fP,\fBPTYPE\fP
  65 .PP
  66 # up to 16 \fBPTYPE\fPs may be present
  67 .PP
  68 .RE
  69 The \fIRTYPE\fP part specifies the callback's return type and
  70 the \fBPTYPE\fPs right to the colon specify the callback's
  71 parameter list, except for the first and the last arguments which
  72 are always pointers.
  73 .PP
  74
  75 .SS Parameter types
  76 Currently, the following types are supported:
  77 .TP 12
  78 \fIVOID
  79 indicates no return type, or no extra parameters. if \fIVOID\fP is used as
  80 the parameter list, no additional parameters may be present.
  81 .TP 12
  82 \fIBOOLEAN
  83 for boolean types (gboolean)
  84 .TP 12
  85 \fICHAR
  86 for signed char types (gchar)
  87 .TP 12
  88 \fIUCHAR
  89 for unsigned char types (guchar)
  90 .TP 12
  91 \fIINT
  92 for signed integer types (gint)
  93 .TP 12
  94 \fIUINT
  95 for unsigned integer types (guint)
  96 .TP 12
  97 \fILONG
  98 for signed long integer types (glong)
  99 .TP 12
 100 \fIULONG
 101 for unsigned long integer types (gulong)
 102 .TP 12
 103 \fIENUM
 104 for enumeration types (gint)
 105 .TP 12
 106 \fIFLAGS
 107 for flag enumeration types (guint)
 108 .TP 12
 109 \fIFLOAT
 110 for single-precision float types (gfloat)
 111 .TP 12
 112 \fIDOUBLE
 113 for double-precision float types (gdouble)
 114 .TP 12
 115 \fISTRING
 116 for string types (gchar*)
 117 .TP 12
 118 \fIBOXED
 119 for boxed (anonymous but reference counted) types (GBoxed*)
 120 .TP 12
 121 \fIPOINTER
 122 for anonymous pointer types (gpointer)
 123 .TP 12
 124 \fIOBJECT
 125 for GObject or derived types (GObject*)
 126 .TP 12
 127 \fINONE
 128 deprecated alias for \fIVOID\fP
 129 .TP 12
 130 \fIBOOL
 131 deprecated alias for \fIBOOLEAN\fP
 132
 133 .SH EXAMPLE
 134 To generate marshallers for the following callback functions:
 135 .PP
 136 .RS
 137 .nf
 138 void   foo (gpointer data1,
 139             gpointer data2);
 140 void   bar (gpointer data1,
 141             gint     param1,
 142             gpointer data2);
 143 gfloat baz (gpointer data1,
 144             gboolean param1,
 145             guchar   param2,
 146             gpointer data2);
 147 .fi
 148 .RE
 149 .PP
 150 The marshaller list has to look like this:
 151 .PP
 152 .RS
 153 .nf
 154 VOID:VOID
 155 VOID:INT
 156 FLOAT:BOOLEAN,UCHAR
 157 .fi
 158 .RE
 159 .PP
 160 The generated marshallers have the arguments encoded
 161 in their function name. For this particular list, they
 162 are
 163 g_cclosure_marshal_VOID__VOID(),
 164 g_cclosure_marshal_VOID__INT(),
 165 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
 166 .PP
 167 They can be used directly for GClosures or be passed in as
 168 the GSignalCMarshaller c_marshaller; argument upon creation
 169 of signals:
 170 .PP
 171 .nf
 172 GClosure *cc_foo, *cc_bar, *cc_baz;
 173
 174 cc_foo = g_cclosure_new (NULL, foo, NULL);
 175 g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID);
 176 cc_bar = g_cclosure_new (NULL, bar, NULL);
 177 g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT);
 178 cc_baz = g_cclosure_new (NULL, baz, NULL);
 179 g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR);
 180 .fi
 181 .PP
 182
 183
 184 .SH SEE ALSO
 185 \fB
 186 glib-config(1)
 187 \fP
 188
 189 .SH BUGS
 190 None known yet.
 191
 192 .SH AUTHOR
 193 .B glib-genmarshal
 194 has been written by Tim Janik <timj@gtk.org>.
 195 .PP
 196 This manual page was provided by Tim Janik <timj@gtk.org>.