From 266ec4aac04cb8666234f18baa38ff6387f40cb3 Mon Sep 17 00:00:00 2001 From: Andrew Bartlett Date: Mon, 24 Feb 2003 03:09:08 +0000 Subject: Merge doxygen, signed/unsigned, const and other small fixes from HEAD to 3.0. Andrew Bartlett (This used to be commit 9ef0d40c3f8aef52ab321dc065264c42065bc876) --- source3/lib/charcnv.c | 175 ++++++++++++++++++++++++++------------------------ 1 file changed, 92 insertions(+), 83 deletions(-) (limited to 'source3/lib/charcnv.c') 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 - * not 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 + *
+ *
STR_TERMINATE
means include the null termination
+ *
STR_UPPER
means uppercase in the destination
+ *
+ * + * @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: + *
+ *
STR_TERMINATE
+ *
STR_TERMINATE means the string in @p src + * is null terminated, and src_len is ignored.
+ *
+ * + * @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: + * + *
+ *
STR_TERMINATE
means include the null termination. + *
STR_UPPER
means uppercase in the destination. + *
STR_NOALIGN
means don't do alignment. + *
+ * + * @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) { -- cgit