From 5fc4248b74c429945ccbed1c819aa33da58a79ff Mon Sep 17 00:00:00 2001 From: Reuben Thomas Date: Tue, 25 Feb 2025 00:56:07 +0000 Subject: [PATCH] doc: point to iconv(3) and iconv(3posix) for more details about iconv MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documentation in GLib of iconv is forgivably brief. Advanced users (e.g. for streaming use, for which this API is recommended over the simpler GLib APIs) will want to know more detail about what happens when there’s an error: without knowing, you can’t really use this function for streaming. Point to both iconv(3posix), which gives the fully-portable details, i.e. all that a user of GLib can rely on, and iconv(3), which is rather easier to read, and may be of interest to those writing GNU-specific code, or who know that their GLib is built with libiconv. The API already promises that it’s the “[s]ame as the standard UNIX routine iconv()”, so it’s quite safe to point to the relevant man pages; looking at the source code bears this out, as g_iconv merely calls iconv. --- glib/gconvert.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/glib/gconvert.c b/glib/gconvert.c index 55cc3d5bd..c6a244148 100644 --- a/glib/gconvert.c +++ b/glib/gconvert.c @@ -172,6 +172,9 @@ g_iconv_open (const gchar *to_codeset, * used), or it may return -1 and set an error such as %EILSEQ, in such a * situation. * + * See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an + * error occurs. + * * Returns: count of non-reversible conversions, or -1 on error **/ gsize