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