gnu/dist/gettext/gettext-runtime/man/bind_textdomain_codeset.3.in

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   GNU gettext source code and manual
  11 .\"   LI18NUX 2000 Globalization Specification
  12 .\"
  13 .TH BIND_TEXTDOMAIN_CODESET 3 "May 2001" "GNU gettext @VERSION@"
  14 .SH NAME
  15 bind_textdomain_codeset \- set encoding of message translations
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <libintl.h>
  19 .sp
  20 .BI "char * bind_textdomain_codeset (const char * " domainname ,
  21 .BI "                                const char * " codeset );
  22 .fi
  23 .SH DESCRIPTION
  24 The \fBbind_textdomain_codeset\fP function sets the output codeset for message
  25 catalogs for domain \fIdomainname\fP.
  26 .PP
  27 A message domain is a set of translatable \fImsgid\fP messages. Usually,
  28 every software package has its own message domain.
  29 .PP
  30 By default, the \fBgettext\fP family of functions returns translated messages
  31 in the locale's character encoding, which can be retrieved as
  32 \fBnl_langinfo(CODESET)\fP. The need for calling \fBbind_textdomain_codeset\fP
  33 arises for programs which store strings in a locale independent way (e.g.
  34 UTF-8) and want to avoid an extra character set conversion on the returned
  35 translated messages.
  36 .PP
  37 \fIdomainname\fP must be a non-empty string.
  38 .PP
  39 If \fIcodeset\fP is not NULL, it must be a valid encoding name which can be
  40 used for the \fBiconv_open\fP function. The \fBbind_textdomain_codeset\fP
  41 function sets the output codeset for message catalogs belonging to domain
  42 \fIdomainname\fP to \fIcodeset\fP. The function makes copies of the argument
  43 strings as needed.
  44 .PP
  45 If \fIcodeset\fP is NULL, the function returns the previously set codeset for
  46 domain \fIdomainname\fP. The default is NULL, denoting the locale's character
  47 encoding.
  48 .SH "RETURN VALUE"
  49 If successful, the \fBbind_textdomain_codeset\fP function returns the current
  50 codeset for domain \fIdomainname\fP, after possibly changing it. The resulting
  51 string is valid until the next \fBbind_textdomain_codeset\fP call for the same
  52 \fIdomainname\fP and must not be modified or freed. If a memory allocation
  53 failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns NULL. If no
  54 codeset has been set for domain \fIdomainname\fP, it returns NULL.
  55 .SH ERRORS
  56 The following error can occur, among others:
  57 .TP
  58 .B ENOMEM
  59 Not enough memory available.
  60 .SH BUGS
  61 The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid
  62 warnings in C code predating ANSI C.
  63 .SH "SEE ALSO"
  64 .BR gettext (3),
  65 .BR dgettext (3),
  66 .BR dcgettext (3),
  67 .BR ngettext (3),
  68 .BR dngettext (3),
  69 .BR dcngettext (3),
  70 .BR textdomain (3),
  71 .BR nl_langinfo (3),
  72 .BR iconv_open (3)