From 8524788abf564fb7927873ff3fbc8056c6f02195 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Roman=20=C5=BDilka?= Date: Sun, 11 Feb 2024 16:51:04 +0100 Subject: [PATCH] tty/vt: Corrected doc of vc_sanitize_unicode(), vc_translate_unicode() MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Corrected the doc of vc_sanitize_unicode() and vc_translate_unicode(), tightly coupled functions which parse UTF-8 byte sequences. 1. Desc. of @rescan corresponded to the meaning of the return value -1. Corrected + added "Return:" section. 2. Replaced the ambiguous "character" with "code point" or "byte". Signed-off-by: Roman Žilka Link: https://lore.kernel.org/r/bee9faa8-0ea7-4411-bf77-3cb2e06385c7@gmail.com Signed-off-by: Greg Kroah-Hartman --- drivers/tty/vt/vt.c | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c index 463be4e48dc8f..4342c47285fe8 100644 --- a/drivers/tty/vt/vt.c +++ b/drivers/tty/vt/vt.c @@ -2780,7 +2780,7 @@ static inline int vc_translate_ascii(const struct vc_data *vc, int c) /** * vc_sanitize_unicode - Replace invalid Unicode code points with ``U+FFFD`` - * @c: the received character, or ``U+FFFD`` for invalid sequences. + * @c: the received code point */ static inline int vc_sanitize_unicode(const int c) { @@ -2793,13 +2793,21 @@ static inline int vc_sanitize_unicode(const int c) /** * vc_translate_unicode - Combine UTF-8 into Unicode in &vc_data.vc_utf_char * @vc: virtual console - * @c: character to translate - * @rescan: we return true if we need more (continuation) data + * @c: UTF-8 byte to translate + * @rescan: set to true iff @c wasn't consumed here and needs to be re-processed * - * * &vc_data.vc_utf_char is the being-constructed unicode character. + * * &vc_data.vc_utf_char is the being-constructed Unicode code point. * * &vc_data.vc_utf_count is the number of continuation bytes still expected to * arrive. * * &vc_data.vc_npar is the number of continuation bytes arrived so far. + * + * Return: + * * %-1 - Input OK so far, @c consumed, further bytes expected. + * * %0xFFFD - Possibility 1: input invalid, @c may have been consumed (see + * desc. of @rescan). Possibility 2: input OK, @c consumed, + * ``U+FFFD`` is the resulting code point. ``U+FFFD`` is valid, + * ``REPLACEMENT CHARACTER``. + * * otherwise - Input OK, @c consumed, resulting code point returned. */ static int vc_translate_unicode(struct vc_data *vc, int c, bool *rescan) { -- 2.30.2