| 1 |
.\" Copyright (c) Bruno Haible <[email protected]> |
| 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 "November 2024" "GNU gettext 0.26" |
| 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) |