Fixing issues according to @plusvic 's advice

 * Limited lines to 80 chars
 * include callback is now using its own user_data and does not conflict with other callbacks
 * Copying include callback result to the stack before pushing it into the flex scanner
 * yara's memory management functions are now exposed through the API
 * Making the lexer reponsible for freeing the memory allocated by the include callback
 * Updating docs accordingly

docs/capi.rst

@@ -69,10 +69,14 @@ However, if you want to fetch the imported rules from another source (eg: from a
 database or remote service), a callback function can be set with
 :c:func:`yr_compiler_set_include_callback`.
 The callback receives the following parameters:
- *``include_name``: name of the requested file.
- *``calling_rule_filename``: the requesting file name (NULL if not a file).
- *``calling_rule_namespace``: namespace (NULL if undefined).
-And should return the requested file as a string.
+ * ``include_name``: name of the requested file.
+ * ``calling_rule_filename``: the requesting file name (NULL if not a file).
+ * ``calling_rule_namespace``: namespace (NULL if undefined).
+ * ``user_data`` pointer is the same you passed to
+ :c:func:`yr_compiler_set_include_callback`.
+It should return the requested file's content as a string. The memory for this string
+should be allocated by the callback function (yr_malloc can be used) but will
+be automatically freed by the yara compiler.
 
 The callback function has the following prototype:
 
@@ -695,6 +699,31 @@ Functions
   Enables the specified rule. After being disabled with :c:func:`yr_rule_disable`
   a rule can be enabled again by using this function.
 
+.. c:function:: void* yr_calloc(size_t count, size_t size);
+
+  Cross-platform wrapper for HeapAlloc on Windows and calloc on other platforms.
+
+.. c:function:: void* yr_malloc(size_t size);
+
+  Cross-platform wrapper for HeapAlloc on Windows and malloc on other platforms.
+
+.. c:function:: void* yr_realloc(void* ptr, size_t size);
+
+  Cross-platform wrapper for HeapReAlloc on Windows and realloc on other platforms.
+
+.. c:function:: void yr_free(void* ptr);
+
+  Cross-platform wrapper for HeapFree on Windows and free on other platforms.
+
+.. c:function:: char* yr_strdup(const char *str);
+
+  Allocates a new buffer the same size as str and copies str to the new buffer.
+
+.. c:function:: char* yr_strdup(const char *str, size_t n);
+
+  Allocates a new buffer of size n and copies the n first character of str.
+
+
 Error codes
 -----------
 

libyara/compiler.c

@@ -189,7 +189,7 @@ YR_API void yr_compiler_set_include_callback(
     void* user_data)
 {
   compiler->include_callback = include_callback;
-  compiler->user_data = user_data;
+  compiler->incl_clbk_user_data = user_data;
 }
 
 

libyara/include/yara.h

@@ -39,5 +39,6 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "yara/error.h"
 #include "yara/stream.h"
 #include "yara/hash.h"
+#include "yara/mem.h"
 
 #endif

libyara/include/yara/compiler.h

@@ -121,6 +121,7 @@ typedef struct _YR_COMPILER
 
   char              include_base_dir[MAX_PATH];
   void*             user_data;
+  void*             incl_clbk_user_data;
 
   YR_COMPILER_CALLBACK_FUNC  callback;
   YR_COMPILER_INCLUDE_CALLBACK_FUNC include_callback;

libyara/include/yara/mem.h

@@ -31,6 +31,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #define YR_MEM_H
 
 #include <stdio.h>
+#include <yara/utils.h>
 
 #ifdef DMALLOC
 
@@ -45,24 +46,24 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 #else
 
-void* yr_calloc(
+YR_API void* yr_calloc(
     size_t count,
     size_t size);
 
-void* yr_malloc(
+YR_API void* yr_malloc(
     size_t size);
 
-void* yr_realloc(
+YR_API void* yr_realloc(
     void* ptr,
     size_t size);
 
-void yr_free(
+YR_API void yr_free(
     void *ptr);
 
-char* yr_strdup(
+YR_API char* yr_strdup(
     const char *str);
 
-char* yr_strndup(
+YR_API char* yr_strndup(
 	const char *str, size_t n);
 
 #endif