2 files changed, 20 insertions, 2 deletions
diff --git a/src/xine-utils/utils.c b/src/xine-utils/utils.c
index 48ceef688..4085d65ee 100644
--- a/src/xine-utils/utils.c
+++ b/src/xine-utils/utils.c
@@ -236,7 +236,25 @@ static const lang_locale_t lang_locales[] = {
   { NULL,       NULL,          NULL,          NULL       }
 };
 
-
+/**
+ * @brief Allocate and clean memory size_t 'size', then return the
+ *        pointer to the allocated memory.
+ * @param size Size of the memory area to allocate.
+ *
+ * @return A pointer to the allocated memory area, or NULL in case of
+ *         error.
+ *
+ * The behaviour of this function differs from standard malloc() as
+ * xine_xmalloc(0) will not return a NULL pointer, but rather a
+ * pointer to a memory area of size 1 byte.
+ *
+ * The NULL value is only ever returned in case of an error in
+ * malloc(), and is reported to stderr stream.
+ *
+ * @deprecated This function has been deprecated, as the behaviour of
+ *             allocating a 1 byte memory area on zero size is almost
+ *             never desired, and the function is thus mostly misused.
+ */
 void *xine_xmalloc(size_t size) {
   void *ptr;
 
diff --git a/src/xine-utils/xineutils.h b/src/xine-utils/xineutils.h
index 2099bf7f3..89aff96bf 100644
--- a/src/xine-utils/xineutils.h
+++ b/src/xine-utils/xineutils.h
@@ -621,7 +621,7 @@ void xine_profiler_print_results (void) XINE_PROTECTED;
  * Allocate and clean memory size_t 'size', then return the pointer
  * to the allocated memory.
  */
-void *xine_xmalloc(size_t size) XINE_MALLOC XINE_PROTECTED;
+void *xine_xmalloc(size_t size) XINE_MALLOC XINE_DEPRECATED XINE_PROTECTED;
 
 /*
  * Same as above, but memory is aligned to 'alignement'.