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 .TP 12
 128 \fIPOINTER
 129 for anonymous pointer types (gpointer)
 130 .TP 12
 131 \fIOBJECT
 132 for GObject or derived types (GObject*)
 133 .TP 12
 134 \fINONE
 135 deprecated alias for \fIVOID\fP
 136 .TP 12
 137 \fIBOOL
 138 deprecated alias for \fIBOOLEAN\fP
 139
 140 .SH EXAMPLE
 141 To generate marshallers for the following callback functions:
 142 .PP
 143 .RS
 144 .nf
 145 void   foo (gpointer data1,
 146             gpointer data2);
 147 void   bar (gpointer data1,
 148             gint     param1,
 149             gpointer data2);
 150 gfloat baz (gpointer data1,
 151             gboolean param1,
 152             guchar   param2,
 153             gpointer data2);
 154 .fi
 155 .RE
 156 .PP
 157 The marshaller list has to look like this:
 158 .PP
 159 .RS
 160 .nf
 161 VOID:VOID
 162 VOID:INT
 163 FLOAT:BOOLEAN,UCHAR
 164 .fi
 165 .RE
 166 .PP
 167 The generated marshallers have the arguments encoded
 168 in their function name. For this particular list, they
 169 are
 170 g_cclosure_marshal_VOID__VOID(),
 171 g_cclosure_marshal_VOID__INT(),
 172 g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR().
 173 .PP
 174 They can be used directly for GClosures or be passed in as
 175 the GSignalCMarshaller c_marshaller; argument upon creation
 176 of signals:
 177 .PP
 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 .PP
 189
 190
 191 .SH SEE ALSO
 192 \fB
 193 glib-mkenums(1)
 194 \fP
 195
 196 .SH BUGS
 197 None known yet.
 198
 199 .SH AUTHOR
 200 .B glib-genmarshal
 201 has been written by Tim Janik <timj@gtk.org>.
 202 .PP
 203 This manual page was provided by Tim Janik <timj@gtk.org>.