* Fixed libcaca prototypes so that all functions use the errno mechanism

and return a value.

caca/caca.c

@@ -23,6 +23,9 @@
 #if !defined(__KERNEL__)
 #   include <stdlib.h>
 #   include <string.h>
+#   if defined(HAVE_ERRNO_H)
+#       include <errno.h>
+#   endif
 #endif
 
 #include "cucul.h"
@@ -30,7 +33,7 @@
 #include "caca.h"
 #include "caca_internals.h"
 
-static int caca_init_driver(caca_display_t *dp);
+static int caca_select_driver(caca_display_t *dp);
 
 /** \brief Attach a caca graphical context to a cucul canvas.
  *
@@ -39,6 +42,10 @@ static int caca_init_driver(caca_display_t *dp);
  *  libcucul canvas. Everything that gets drawn in the libcucul canvas can
  *  then be displayed by the libcaca driver.
  *
+ *  If an error occurs, NULL is returned and \b errno is set accordingly:
+ *  - \c ENOMEM Not enough memory.
+ *  - \c ENODEV Graphical device could not be initialised.
+ *
  *  \param cv The cucul cavas.
  *  \return The caca graphical context or NULL if an error occurred.
  */
@@ -46,17 +53,31 @@ caca_display_t * caca_create_display(cucul_canvas_t * cv)
 {
     caca_display_t *dp = malloc(sizeof(caca_display_t));
 
+    if(!dp)
+    {
+#if defined(HAVE_ERRNO_H)
+        errno = ENOMEM;
+#endif
+        return NULL;
+    }
+
     dp->cv = cv;
 
-    if(caca_init_driver(dp))
+    if(caca_select_driver(dp))
     {
         free(dp);
+#if defined(HAVE_ERRNO_H)
+        errno = ENODEV;
+#endif
         return NULL;
     }
 
     if(dp->drv.init_graphics(dp))
     {
         free(dp);
+#if defined(HAVE_ERRNO_H)
+        errno = ENODEV;
+#endif
         return NULL;
     }
 
@@ -99,20 +120,25 @@ caca_display_t * caca_create_display(cucul_canvas_t * cv)
  *  libcucul canvas continues to exist and other graphical contexts can be
  *  attached to it afterwards.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca graphical context.
+ *  \return This function always returns 0.
  */
-void caca_free_display(caca_display_t *dp)
+int caca_free_display(caca_display_t *dp)
 {
     dp->drv.end_graphics(dp);
     dp->cv->refcount--;
     free(dp);
+
+    return 0;
 }
 
 /*
  * XXX: The following functions are local.
  */
 
-static int caca_init_driver(caca_display_t *dp)
+static int caca_select_driver(caca_display_t *dp)
 {
 #if defined(HAVE_GETENV) && defined(HAVE_STRCASECMP)
     char *var = getenv("CACA_DRIVER");

caca/caca.h

@@ -150,9 +150,9 @@ enum caca_key
  *
  *  @{ */
 caca_display_t * caca_create_display(cucul_canvas_t *);
-void caca_free_display(caca_display_t *);
-void caca_refresh_display(caca_display_t *);
-void caca_set_display_time(caca_display_t *, unsigned int);
+int caca_free_display(caca_display_t *);
+int caca_refresh_display(caca_display_t *);
+int caca_set_display_time(caca_display_t *, unsigned int);
 unsigned int caca_get_display_time(caca_display_t *);
 unsigned int caca_get_display_width(caca_display_t *);
 unsigned int caca_get_display_height(caca_display_t *);
@@ -168,7 +168,7 @@ int caca_set_display_title(caca_display_t *, char const *);
 int caca_get_event(caca_display_t *, unsigned int, caca_event_t *, int);
 unsigned int caca_get_mouse_x(caca_display_t *);
 unsigned int caca_get_mouse_y(caca_display_t *);
-void caca_set_mouse(caca_display_t *, int);
+int caca_set_mouse(caca_display_t *, int);
 /*  @} */
 
 #ifdef __cplusplus

caca/driver_conio.c

@@ -79,7 +79,7 @@ static int conio_end_graphics(caca_display_t *dp)
 
 static int conio_set_display_title(caca_display_t *dp, char const *title)
 {
-    return 0;
+    return -1;
 }
 
 static unsigned int conio_get_display_width(caca_display_t *dp)

caca/driver_ncurses.c

@@ -178,7 +178,7 @@ static int ncurses_end_graphics(caca_display_t *dp)
 
 static int ncurses_set_display_title(caca_display_t *dp, char const *title)
 {
-    return 0;
+    return -1;
 }
 
 static unsigned int ncurses_get_display_width(caca_display_t *dp)

caca/driver_raw.c

@@ -39,7 +39,7 @@ static int raw_end_graphics(caca_display_t *dp)
 
 static int raw_set_display_title(caca_display_t *dp, char const *title)
 {
-    return 0;
+    return -1;
 }
 
 static unsigned int raw_get_display_width(caca_display_t *dp)

caca/driver_slang.c

@@ -183,7 +183,7 @@ static int slang_end_graphics(caca_display_t *dp)
 static int slang_set_display_title(caca_display_t *dp, char const *title)
 {
     /* FIXME */
-    return 0;
+    return -1;
 }
 
 static unsigned int slang_get_display_width(caca_display_t *dp)

caca/driver_vga.c

@@ -97,7 +97,7 @@ static int vga_end_graphics(caca_display_t *dp)
 static int vga_set_display_title(caca_display_t *dp, char const *title)
 {
     /* Unsupported, of course. */
-    return 0;
+    return -1;
 }
 
 static unsigned int vga_get_display_width(caca_display_t *dp)

caca/event.c

@@ -44,7 +44,7 @@ static int _lowlevel_event(caca_display_t *, caca_event_t *);
  *
  *  This function polls the event queue for mouse or keyboard events matching
  *  the event mask and returns the first matching event. Non-matching events
- *  are discarded. \c event_mask must have a non-zero value.
+ *  are discarded. If \c event_mask is zero, the function returns immediately.
  *
  *  The timeout value tells how long this function needs to wait for an
  *  event. A value of zero returns immediately and the function returns zero
@@ -55,6 +55,8 @@ static int _lowlevel_event(caca_display_t *, caca_event_t *);
  *  received. If null, the function will return but no information about
  *  the event will be sent.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca graphical context.
  *  \param event_mask Bitmask of requested events.
  *  \param timeout A timeout value in microseconds, -1 for blocking behaviour
@@ -117,6 +119,8 @@ int caca_get_event(caca_display_t *dp, unsigned int event_mask,
  *  drivers are being used, because mouse position is only detected when
  *  the mouse is clicked. Other drivers such as X11 work well.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca graphical context.
  *  \return The X mouse coordinate.
  */
@@ -135,6 +139,8 @@ unsigned int caca_get_mouse_x(caca_display_t *dp)
  *  drivers are being used, because mouse position is only detected when
  *  the mouse is clicked. Other drivers such as X11 work well.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca graphical context.
  *  \return The Y mouse coordinate.
  */

caca/graphics.c

@@ -18,6 +18,12 @@
 #include "config.h"
 #include "common.h"
 
+#if !defined(__KERNEL__)
+#   if defined(HAVE_ERRNO_H)
+#       include <errno.h>
+#   endif
+#endif
+
 #include "caca.h"
 #include "caca_internals.h"
 #include "cucul.h"
@@ -26,15 +32,25 @@
 /** \brief Set the display title.
  *
  *  If libcaca runs in a window, try to change its title. This works with
- *  the X11 and Win32 drivers.
+ *  the OpenGL, X11 and Win32 drivers.
+ *
+ *  If an error occurs, -1 is returned and \b errno is set accordingly:
+ *  - \c ENOSYS Display driver does not support setting the window title.
  *
  *  \param dp The libcaca display context.
  *  \param title The desired display title.
- *  \return 0 upon success, a non-zero value if an error occurs.
+ *  \return 0 upon success, -1 if an error occurred.
  */
 int caca_set_display_title(caca_display_t *dp, char const *title)
 {
-    return dp->drv.set_display_title(dp, title);
+    int ret = dp->drv.set_display_title(dp, title);
+
+#if defined(HAVE_ERRNO_H)
+    if(ret)
+        errno = ENOSYS;
+#endif
+
+    return ret;
 }
 
 /** \brief Get the display width.
@@ -44,6 +60,8 @@ int caca_set_display_title(caca_display_t *dp, char const *title)
  *  or if there is no way to know the font size, most drivers will assume a
  *  6x10 font is being used. Note that the units are not necessarily pixels.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca display context.
  *  \return The display width.
  */
@@ -59,6 +77,8 @@ unsigned int caca_get_display_width(caca_display_t *dp)
  *  or if there is no way to know the font size, assume a 6x10 font is being
  *  used. Note that the units are not necessarily pixels.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca display context.
  *  \return The display height.
  */
@@ -76,12 +96,16 @@ unsigned int caca_get_display_height(caca_display_t *dp)
  *  If the argument is zero, constant framerate is disabled. This is the
  *  default behaviour.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca display context.
  *  \param usec The refresh delay in microseconds.
+ *  \return This function always returns 0.
  */
-void caca_set_display_time(caca_display_t *dp, unsigned int usec)
+int caca_set_display_time(caca_display_t *dp, unsigned int usec)
 {
     dp->delay = usec;
+    return 0;
 }
 
 /** \brief Get the display's average rendering time.
@@ -92,6 +116,8 @@ void caca_set_display_time(caca_display_t *dp, unsigned int usec)
  *  average rendering time will not be considerably shorter than the requested
  *  delay even if the real rendering time was shorter.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca display context.
  *  \return The render time in microseconds.
  */
@@ -112,9 +138,12 @@ unsigned int caca_get_display_time(caca_display_t *dp)
  *  a time range shorter than the value set with caca_set_display_time(),
  *  the second call will be delayed before performing the screen refresh.
  *
+ *  This function never fails.
+ *
  *  \param dp The libcaca display context.
+ *  \return This function always returns 0.
  */
-void caca_refresh_display(caca_display_t *dp)
+int caca_refresh_display(caca_display_t *dp)
 {
 #if !defined(_DOXYGEN_SKIP_ME)
 #define IDLE_USEC 5000
@@ -147,6 +176,8 @@ void caca_refresh_display(caca_display_t *dp)
     /* If we drifted too much, it's bad, bad, bad. */
     if(dp->lastticks > (int)dp->delay)
         dp->lastticks = 0;
+
+    return 0;
 }
 
 /** \brief Show or hide the mouse pointer.
@@ -154,14 +185,26 @@ void caca_refresh_display(caca_display_t *dp)
  *  This function shows or hides the mouse pointer, for devices that
  *  support it.
  *
+ *  If an error occurs, -1 is returned and \b errno is set accordingly:
+ *  - \c ENOSYS Display driver does not support hiding the mouse pointer.
+ *
  *  \param dp The libcaca display context.
  *  \param flag 0 hides the pointer, 1 shows the system's default pointer
  *              (usually an arrow). Other values are reserved for future use.
+ *  \return 0 upon success, -1 if an error occurred.
  */
-void caca_set_mouse(caca_display_t *dp, int flag)
+int caca_set_mouse(caca_display_t *dp, int flag)
 {
-    if(dp->drv.set_mouse)
-        dp->drv.set_mouse(dp, flag);
+    if(!dp->drv.set_mouse)
+    {
+#if defined(HAVE_ERRNO_H)
+        errno = ENOSYS;
+#endif
+        return -1;
+    }
+
+    dp->drv.set_mouse(dp, flag);
+    return 0;
 }
 
 /*