Merge doxygen, signed/unsigned, const and other small fixes from HEAD to 3.0.

Andrew Bartlett
(This used to be commit 9ef0d40c3f8aef52ab321dc065264c42065bc876)

1 files changed, 92 insertions, 83 deletions

diff --git a/source3/lib/charcnv.c b/source3/lib/charcnv.c
index 4ac10a2e74..bffa2a378c 100644
--- a/source3/lib/charcnv.c
+++ b/source3/lib/charcnv.c
@@ -22,27 +22,22 @@
 */
 #include "includes.h"
 
-/**
- * @file
- *
- * @brief Character-set conversion routines built on our iconv.
- * 
- * @note Samba's internal character set (at least in the 3.0 series)
- * is always the same as the one for the Unix filesystem.  It is
- * <b>not</b> necessarily UTF-8 and may be different on machines that
- * need i18n filenames to be compatible with Unix software.  It does
- * have to be a superset of ASCII.  All multibyte sequences must start
- * with a byte with the high bit set.
- */
-
 static pstring cvtbuf;
 
 static smb_iconv_t conv_handles[NUM_CHARSETS][NUM_CHARSETS];
 
-/****************************************************************************
- Return the name of a charset to give to iconv().
-****************************************************************************/
+/**
+ * @file
+ *
+ * Character set conversion routines.
+ *
+ * @sa lib/iconv.c
+ **/
+
 
+/**
+ * Return the name of a charset to give to iconv().
+ **/
 static const char *charset_name(charset_t ch)
 {
 	const char *ret = NULL;
@@ -69,9 +64,9 @@ static void lazy_initialize_conv(void)
 	}
 }
 
-/****************************************************************************
+/**
  Initialize iconv conversion descriptors.
-****************************************************************************/
+**/
 
 void init_iconv(void)
 {
@@ -117,14 +112,12 @@ void init_iconv(void)
 /**
  * Convert string from one encoding to another, making error checking etc
  *
- * @param descriptor conversion descriptor, created in init_iconv()
  * @param src pointer to source string (multibyte or singlebyte)
  * @param srclen length of the source string in bytes
  * @param dest pointer to destination string (multibyte or singlebyte)
  * @param destlen maximal length allowed for string
- * @retval the number of bytes occupied in the destination
+ * @returns the number of bytes occupied in the destination
  **/
-
 size_t convert_string(charset_t from, charset_t to,
 		      void const *src, size_t srclen, 
 		      void *dest, size_t destlen)
@@ -183,7 +176,7 @@ size_t convert_string(charset_t from, charset_t to,
  * @param dest always set at least to NULL
  * @note -1 is not accepted for srclen.
  *
- * @retval Size in bytes of the converted string; or -1 in case of error.
+ * @returns Size in bytes of the converted string; or -1 in case of error.
  **/
 
 size_t convert_string_allocate(charset_t from, charset_t to,
@@ -255,6 +248,7 @@ convert:
 	return destlen;
 }
 
+
 /**
  * Convert between character sets, allocating a new buffer using talloc for the result.
  *
@@ -262,9 +256,8 @@ convert:
  * @param dest always set at least to NULL 
  * @note -1 is not accepted for srclen.
  *
- * @retval Size in bytes of the converted string; or -1 in case of error.
+ * @returns Size in bytes of the converted string; or -1 in case of error.
  **/
-
 size_t convert_string_talloc(TALLOC_CTX *ctx, charset_t from, charset_t to,
 		      		void const *src, size_t srclen, void **dest)
 {
@@ -311,16 +304,20 @@ size_t ucs2_align(const void *base_ptr, const void *p, int flags)
 }
 
 
-/****************************************************************************
-copy a string from a char* unix src to a dos codepage string destination
-return the number of bytes occupied by the string in the destination
-flags can have:
-  STR_TERMINATE means include the null termination
-  STR_UPPER     means uppercase in the destination
-dest_len is the maximum length in bytes allowed in the destination. If dest_len
-is -1 then no maxiumum is used
-****************************************************************************/
-
+/**
+ * Copy a string from a char* unix src to a dos codepage string destination.
+ *
+ * @return the number of bytes occupied by the string in the destination.
+ *
+ * @param flags can include
+ * <dl>
+ * <dt>STR_TERMINATE</dt> <dd>means include the null termination</dd>
+ * <dt>STR_UPPER</dt> <dd>means uppercase in the destination</dd>
+ * </dl>
+ *
+ * @param dest_len the maximum length in bytes allowed in the
+ * destination.  If @p dest_len is -1 then no maximum is used.
+ **/
 size_t push_ascii(void *dest, const char *src, size_t dest_len, int flags)
 {
 	size_t src_len = strlen(src);
@@ -357,16 +354,21 @@ size_t push_pstring(void *dest, const char *src)
 	return push_ascii(dest, src, sizeof(pstring), STR_TERMINATE);
 }
 
-/****************************************************************************
- Copy a string from a dos codepage source to a unix char* destination.
- Flags can have:
-   STR_TERMINATE means the string in src is null terminated.
- if STR_TERMINATE is set then src_len is ignored.
- src_len is the length of the source area in bytes.
- Return the number of bytes occupied by the string in src.
- The resulting string in "dest" is always null terminated.
-****************************************************************************/
-
+/**
+ * Copy a string from a dos codepage source to a unix char* destination.
+ *
+ * The resulting string in "dest" is always null terminated.
+ *
+ * @param flags can have:
+ * <dl>
+ * <dt>STR_TERMINATE</dt>
+ * <dd>STR_TERMINATE means the string in @p src
+ * is null terminated, and src_len is ignored.</dd>
+ * </dl>
+ *
+ * @param src_len is the length of the source area in bytes.
+ * @returns the number of bytes occupied by the string in @p src.
+ **/
 size_t pull_ascii(char *dest, const void *src, size_t dest_len, size_t src_len, int flags)
 {
 	size_t ret;
@@ -403,17 +405,22 @@ size_t pull_ascii_fstring(char *dest, const void *src)
 	return pull_ascii(dest, src, sizeof(fstring), -1, STR_TERMINATE);
 }
 
-/****************************************************************************
- Copy a string from a char* src to a unicode destination.
- Return the number of bytes occupied by the string in the destination.
- Flags can have:
-  STR_TERMINATE means include the null termination.
-  STR_UPPER     means uppercase in the destination.
-  STR_NOALIGN   means don't do alignment.
- dest_len is the maximum length allowed in the destination. If dest_len
- is -1 then no maxiumum is used.
-****************************************************************************/
-
+/**
+ * Copy a string from a char* src to a unicode destination.
+ *
+ * @returns the number of bytes occupied by the string in the destination.
+ *
+ * @param flags can have:
+ *
+ * <dl>
+ * <dt>STR_TERMINATE <dd>means include the null termination.
+ * <dt>STR_UPPER     <dd>means uppercase in the destination.
+ * <dt>STR_NOALIGN   <dd>means don't do alignment.
+ * </dl>
+ *
+ * @param dest_len is the maximum length allowed in the
+ * destination. If dest_len is -1 then no maxiumum is used.
+ **/
 size_t push_ucs2(const void *base_ptr, void *dest, const char *src, size_t dest_len, int flags)
 {
 	size_t len=0;
@@ -447,15 +454,16 @@ size_t push_ucs2(const void *base_ptr, void *dest, const char *src, size_t dest_
 	return len;
 }
 
+
 /**
- * Copy a string from a unix char* src to a UCS2 destination, allocating a buffer using talloc
+ * Copy a string from a unix char* src to a UCS2 destination,
+ * allocating a buffer using talloc().
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  *         or -1 in case of error.
  **/
-
 size_t push_ucs2_talloc(TALLOC_CTX *ctx, smb_ucs2_t **dest, const char *src)
 {
 	size_t src_len = strlen(src)+1;
@@ -464,12 +472,13 @@ size_t push_ucs2_talloc(TALLOC_CTX *ctx, smb_ucs2_t **dest, const char *src)
 	return convert_string_talloc(ctx, CH_UNIX, CH_UCS2, src, src_len, (void **)dest);
 }
 
+
 /**
  * Copy a string from a unix char* src to a UCS2 destination, allocating a buffer
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  *         or -1 in case of error.
  **/
 
@@ -481,7 +490,7 @@ size_t push_ucs2_allocate(smb_ucs2_t **dest, const char *src)
 	return convert_string_allocate(CH_UNIX, CH_UCS2, src, src_len, (void **)dest);	
 }
 
-/****************************************************************************
+/**
  Copy a string from a char* src to a UTF-8 destination.
  Return the number of bytes occupied by the string in the destination
  Flags can have:
@@ -489,7 +498,7 @@ size_t push_ucs2_allocate(smb_ucs2_t **dest, const char *src)
   STR_UPPER     means uppercase in the destination
  dest_len is the maximum length allowed in the destination. If dest_len
  is -1 then no maxiumum is used.
-****************************************************************************/
+**/
 
 size_t push_utf8(void *dest, const char *src, size_t dest_len, int flags)
 {
@@ -527,7 +536,7 @@ size_t push_utf8_pstring(void *dest, const char *src)
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  **/
 
 size_t push_utf8_talloc(TALLOC_CTX *ctx, char **dest, const char *src)
@@ -543,7 +552,7 @@ size_t push_utf8_talloc(TALLOC_CTX *ctx, char **dest, const char *src)
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  **/
 
 size_t push_utf8_allocate(char **dest, const char *src)
@@ -554,7 +563,7 @@ size_t push_utf8_allocate(char **dest, const char *src)
 	return convert_string_allocate(CH_UNIX, CH_UTF8, src, src_len, (void **)dest);	
 }
 
-/****************************************************************************
+/**
  Copy a string from a ucs2 source to a unix char* destination.
  Flags can have:
   STR_TERMINATE means the string in src is null terminated.
@@ -563,7 +572,7 @@ size_t push_utf8_allocate(char **dest, const char *src)
  src_len is the length of the source area in bytes
  Return the number of bytes occupied by the string in src.
  The resulting string in "dest" is always null terminated.
-****************************************************************************/
+**/
 
 size_t pull_ucs2(const void *base_ptr, char *dest, const void *src, size_t dest_len, size_t src_len, int flags)
 {
@@ -615,7 +624,7 @@ size_t pull_ucs2_fstring(char *dest, const void *src)
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  **/
 
 size_t pull_ucs2_talloc(TALLOC_CTX *ctx, char **dest, const smb_ucs2_t *src)
@@ -630,7 +639,7 @@ size_t pull_ucs2_talloc(TALLOC_CTX *ctx, char **dest, const smb_ucs2_t *src)
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  **/
 
 size_t pull_ucs2_allocate(void **dest, const smb_ucs2_t *src)
@@ -640,7 +649,7 @@ size_t pull_ucs2_allocate(void **dest, const smb_ucs2_t *src)
 	return convert_string_allocate(CH_UCS2, CH_UNIX, src, src_len, dest);	
 }
 
-/****************************************************************************
+/**
  Copy a string from a utf-8 source to a unix char* destination.
  Flags can have:
   STR_TERMINATE means the string in src is null terminated.
@@ -648,7 +657,7 @@ size_t pull_ucs2_allocate(void **dest, const smb_ucs2_t *src)
  src_len is the length of the source area in bytes
  Return the number of bytes occupied by the string in src.
  The resulting string in "dest" is always null terminated.
-****************************************************************************/
+**/
 
 size_t pull_utf8(char *dest, const void *src, size_t dest_len, size_t src_len, int flags)
 {
@@ -690,7 +699,7 @@ size_t pull_utf8_fstring(char *dest, const void *src)
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  **/
 
 size_t pull_utf8_talloc(TALLOC_CTX *ctx, char **dest, const char *src)
@@ -705,7 +714,7 @@ size_t pull_utf8_talloc(TALLOC_CTX *ctx, char **dest, const char *src)
  *
  * @param dest always set at least to NULL 
  *
- * @retval The number of bytes occupied by the string in the destination
+ * @returns The number of bytes occupied by the string in the destination
  **/
 
 size_t pull_utf8_allocate(void **dest, const char *src)
@@ -715,7 +724,7 @@ size_t pull_utf8_allocate(void **dest, const char *src)
 	return convert_string_allocate(CH_UTF8, CH_UNIX, src, src_len, dest);	
 }
  
-/****************************************************************************
+/**
  Copy a string from a char* src to a unicode or ascii
  dos codepage destination choosing unicode or ascii based on the 
  flags in the SMB buffer starting at base_ptr.
@@ -727,7 +736,7 @@ size_t pull_utf8_allocate(void **dest, const char *src)
   STR_NOALIGN   means don't do alignment.
  dest_len is the maximum length allowed in the destination. If dest_len
  is -1 then no maxiumum is used.
-****************************************************************************/
+**/
 
 size_t push_string(const void *base_ptr, void *dest, const char *src, size_t dest_len, int flags)
 {
@@ -740,7 +749,7 @@ size_t push_string(const void *base_ptr, void *dest, const char *src, size_t des
 }
 
 
-/****************************************************************************
+/**
  Copy a string from a unicode or ascii source (depending on
  the packet flags) to a char* destination.
  Flags can have:
@@ -752,7 +761,7 @@ size_t push_string(const void *base_ptr, void *dest, const char *src, size_t des
  src_len is the length of the source area in bytes.
  Return the number of bytes occupied by the string in src.
  The resulting string in "dest" is always null terminated.
-****************************************************************************/
+**/
 
 size_t pull_string(const void *base_ptr, char *dest, const void *src, size_t dest_len, size_t src_len, int flags)
 {
@@ -774,12 +783,12 @@ size_t align_string(const void *base_ptr, const char *p, int flags)
 	return 0;
 }
 
-/****************************************************************************
+/**
  Convert from ucs2 to unix charset and return the
  allocated and converted string or NULL if an error occurred.
  You must provide a zero terminated string.
  The returning string will be zero terminated.
-****************************************************************************/
+**/
 
 char *acnv_u2ux(const smb_ucs2_t *src)
 {
@@ -795,12 +804,12 @@ char *acnv_u2ux(const smb_ucs2_t *src)
 		return dest;
 }
 
-/****************************************************************************
+/**
  Convert from unix to ucs2 charset and return the
  allocated and converted string or NULL if an error occurred.
  You must provide a zero terminated string.
  The returning string will be zero terminated.
-****************************************************************************/
+**/
 
 smb_ucs2_t *acnv_uxu2(const char *src)
 {
@@ -816,12 +825,12 @@ smb_ucs2_t *acnv_uxu2(const char *src)
 		return dest;
 }
 
-/****************************************************************************
+/**
  Convert from ucs2 to dos charset and return the
  allocated and converted string or NULL if an error occurred.
  You must provide a zero terminated string.
  The returning string will be zero terminated.
-****************************************************************************/
+**/
 
 char *acnv_u2dos(const smb_ucs2_t *src)
 {
@@ -837,12 +846,12 @@ char *acnv_u2dos(const smb_ucs2_t *src)
 		return dest;
 }
 
-/****************************************************************************
+/**
  Convert from dos to ucs2 charset and return the
  allocated and converted string or NULL if an error occurred.
  You must provide a zero terminated string.
  The returning string will be zero terminated.
-****************************************************************************/
+**/
 
 smb_ucs2_t *acnv_dosu2(const char *src)
 {