--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/dyncallback/dyncallback.3	Thu Mar 19 22:24:28 2015 +0100
@@ -0,0 +1,134 @@
+.\" Copyright (c) 2007-2014 Daniel Adler <dadler AT uni-goettingen DOT de>, 
+.\"                         Tassilo Philipp <tphilipp AT potion-studios DOT com>
+.\" 
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt dyncallback 3
+.Os
+.Sh NAME
+.Nm dyncallback
+.Nd callback interface of dyncall
+.Sh SYNOPSIS
+.In dyncall_callback.h
+.Ft DCCallback *
+.Fn dcbNewCallback "const char * signature" "DCCallbackHandler * funcptr" "void * userdata"
+.Ft void
+.Fn dcbInitCallback "DCCallback * pcb" "const char * signature" "DCCallbackHandler * funcptr" "void * userdata"
+.Ft void
+.Fn dcbFreeCallback "DCCallback * pcb"
+.Ft void
+.Fn dcbGetUserData "DCCallback * pcb"
+.Sh DESCRIPTION
+The
+.Nm
+dyncall library has an interface to create callback objects, that can be passed
+to functions as callback arguments. In other words, a pointer to the callback
+object can be "called", directly. The callback handler then allows iterating
+dynamically over the arguments once called back.
+.Pp
+.Fn dcbNewCallback
+creates a new callback object, where
+.Ar signature
+is a signature string describing the function to be called back (see manual for
+format). This is needed for
+.Nm
+dyncallback to correctly prepare the arguments passed in by the function that
+calls the callback handler. Note that the handler doesn't return the value
+specified in the signature, directly, but simply 'i' or 'f' depending on whether
+it is a integral or floating point type. The return value itself is stored
+where the handler's 3rd parameter points to (see example).
+.Ar funcptr
+is a pointer to the
+.Nm
+dyncallback callback handler (see below), and
+.Ar userdata
+a pointer to arbitrary user data you want to use in the callback handler.
+Use the returned pointer as callback argument in functions requiring a callback
+function pointer.
+.Pp
+.Fn dcbInitCallback
+(re)initialize the callback object.
+.Pp
+.Fn dcbFreeCallback
+destroys and frees the callback handler.
+.Pp
+.Fn dcbGetUserData
+returns a pointer to the userdata passed to the callback object on creation or
+initialization.
+.Pp
+Declaration of a dyncallback handler (following function pointer definition in
+dyncallback/dyncall_callback.h):
+.Bd -literal -offset indent
+char cbHandler(DCCallback* cb,
+               DCArgs*     args,
+               DCValue*    result,
+               void*       userdata);
+.Ed
+.Pp
+.Ar cb is a pointer to the DCCallback object in use
+.Nm
+result is a pointer to a DCValue object in order to store the callback's
+return value (output, to be set by handler). Finally,
+.Ar userdata is a pointer to some user defined data that can be
+set when creating the callback object.
+The handler itself returns a signature character (see manual for format)
+specifying the data type used for
+.Ar result .
+.Sh EXAMPLE
+Let's say, we want to create a callback object and call it. For simplicity, this
+example will omit passing it as a function pointer to a function (e.g. compar
+in qsort(), etc.) and demonstrate calling it, directly. First, we need to define
+our callback handler - the following handler illustrates how to access the passed-
+in arguments:
+.Bd -literal -offset indent
+char cbHandler(DCCallback* cb,
+               DCArgs*     args,
+               DCValue*    result,
+               void*       userdata)
+{
+  int* ud = (int*)userdata;
+  int       arg1 = dcbArgInt     (args);
+  float     arg2 = dcbArgFloat   (args);
+  short     arg3 = dcbArgShort   (args);
+  double    arg4 = dcbArgDouble  (args);
+  long long arg5 = dcbArgLongLong(args);
+
+  // .. do something ..
+
+  result->s = 1244;
+  return 'i';
+}
+.Ed
+.Pp
+Note that the return value of the handler is a signature character, not the
+actual return value, itself, and note that the actual return value is of type
+short.
+Now, let's call it through a DCCallback object:
+.Bd -literal -offset indent
+  DCCallback* cb;
+  short result = 0;
+  int userdata = 1337;
+  cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
+  result = ((short(*)(int, float, short, double, long long))cb)
+    (123, 23.f, 3, 1.82, 9909ll);
+  dcbFreeCallback(cb);
+.Ed
+.Sh SEE ALSO
+.Xr dyncall 3 ,
+.Xr dynload 3
+and the dyncall manual (available in PDF format) for a way more detailed documentation of this
+library.
+.Sh AUTHORS
+.An "Daniel Adler" Aq dadler@uni-goettingen.de
+.An "Tassilo Philipp" Aq tphilipp@potion-studios.com