1*946379e7Schristos<html> 2*946379e7Schristos<head> 3*946379e7Schristos<meta name="generator" content="groff -Thtml, see www.gnu.org"> 4*946379e7Schristos<meta name="Content-Style" content="text/css"> 5*946379e7Schristos<title>GETTEXT</title> 6*946379e7Schristos</head> 7*946379e7Schristos<body> 8*946379e7Schristos 9*946379e7Schristos<h1 align=center>GETTEXT</h1> 10*946379e7Schristos<a href="#NAME">NAME</a><br> 11*946379e7Schristos<a href="#SYNOPSIS">SYNOPSIS</a><br> 12*946379e7Schristos<a href="#DESCRIPTION">DESCRIPTION</a><br> 13*946379e7Schristos<a href="#RETURN VALUE">RETURN VALUE</a><br> 14*946379e7Schristos<a href="#ERRORS">ERRORS</a><br> 15*946379e7Schristos<a href="#BUGS">BUGS</a><br> 16*946379e7Schristos<a href="#SEE ALSO">SEE ALSO</a><br> 17*946379e7Schristos 18*946379e7Schristos<hr> 19*946379e7Schristos<!-- Creator : groff version 1.17 --> 20*946379e7Schristos<a name="NAME"></a> 21*946379e7Schristos<h2>NAME</h2> 22*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 23*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 24*946379e7Schristos<tr valign="top" align="left"> 25*946379e7Schristos<td width="10%"></td><td width="90%"> 26*946379e7Schristosgettext, dgettext, dcgettext - translate message</td></table> 27*946379e7Schristos<a name="SYNOPSIS"></a> 28*946379e7Schristos<h2>SYNOPSIS</h2> 29*946379e7Schristos 30*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 31*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 32*946379e7Schristos<tr valign="top" align="left"> 33*946379e7Schristos<td width="10%"></td><td width="90%"> 34*946379e7Schristos<pre><b>#include <libintl.h> 35*946379e7Schristos 36*946379e7Schristoschar * gettext (const char *</b> <i>msgid</i><b>); 37*946379e7Schristoschar * dgettext (const char *</b> <i>domainname</i><b>, const char *</b> <i>msgid</i><b>); 38*946379e7Schristoschar * dcgettext (const char *</b> <i>domainname</i><b>, const char *</b> <i>msgid</i><b>, 39*946379e7Schristos int</b> <i>category</i><b>); 40*946379e7Schristos</b></pre></td></table> 41*946379e7Schristos<a name="DESCRIPTION"></a> 42*946379e7Schristos<h2>DESCRIPTION</h2> 43*946379e7Schristos 44*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 45*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 46*946379e7Schristos<tr valign="top" align="left"> 47*946379e7Schristos<td width="10%"></td><td width="90%"> 48*946379e7SchristosThe <b>gettext</b>, <b>dgettext</b> and <b>dcgettext</b> 49*946379e7Schristosfunctions attempt to translate a text string into the user's 50*946379e7Schristosnative language, by looking up the translation in a message 51*946379e7Schristoscatalog.</td></table> 52*946379e7Schristos 53*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 54*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 55*946379e7Schristos<tr valign="top" align="left"> 56*946379e7Schristos<td width="10%"></td><td width="90%"> 57*946379e7SchristosThe <i>msgid</i> argument identifies the message to be 58*946379e7Schristostranslated. By convention, it is the English version of the 59*946379e7Schristosmessage, with non-ASCII characters replaced by ASCII 60*946379e7Schristosapproximations. This choice allows the translators to work 61*946379e7Schristoswith message catalogs, called PO files, that contain both 62*946379e7Schristosthe English and the translated versions of each message, and 63*946379e7Schristoscan be installed using the <b>msgfmt</b> 64*946379e7Schristosutility.</td></table> 65*946379e7Schristos 66*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 67*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 68*946379e7Schristos<tr valign="top" align="left"> 69*946379e7Schristos<td width="10%"></td><td width="90%"> 70*946379e7SchristosA message domain is a set of translatable <i>msgid</i> 71*946379e7Schristosmessages. Usually, every software package has its own 72*946379e7Schristosmessage domain. The domain name is used to determine the 73*946379e7Schristosmessage catalog where the translation is looked up; it must 74*946379e7Schristosbe a non-empty string. For the <b>gettext</b> function, it 75*946379e7Schristosis specified through a preceding <b>textdomain</b> call. For 76*946379e7Schristosthe <b>dgettext</b> and <b>dcgettext</b> functions, it is 77*946379e7Schristospassed as the <i>domainname</i> argument; if this argument 78*946379e7Schristosis NULL, the domain name specified through a preceding 79*946379e7Schristos<b>textdomain</b> call is used instead.</td></table> 80*946379e7Schristos 81*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 82*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 83*946379e7Schristos<tr valign="top" align="left"> 84*946379e7Schristos<td width="10%"></td><td width="90%"> 85*946379e7SchristosTranslation lookup operates in the context of the current 86*946379e7Schristoslocale. For the <b>gettext</b> and <b>dgettext</b> 87*946379e7Schristosfunctions, the <b>LC_MESSAGES</b> locale facet is used. It 88*946379e7Schristosis determined by a preceding call to the <b>setlocale</b> 89*946379e7Schristosfunction. <b>setlocale(LC_ALL,"")</b> initializes 90*946379e7Schristosthe <b>LC_MESSAGES</b> locale based on the first nonempty 91*946379e7Schristosvalue of the three environment variables <b>LC_ALL</b>, 92*946379e7Schristos<b>LC_MESSAGES</b>, <b>LANG</b>; see <b>setlocale</b>(3). 93*946379e7SchristosFor the <b>dcgettext</b> function, the locale facet is 94*946379e7Schristosdetermined by the <i>category</i> argument, which should be 95*946379e7Schristosone of the <b>LC_xxx</b> constants defined in the 96*946379e7Schristos<locale.h> header, excluding <b>LC_ALL</b>. In both 97*946379e7Schristoscases, the functions also use the <b>LC_CTYPE</b> locale 98*946379e7Schristosfacet in order to convert the translated message from the 99*946379e7Schristostranslator's codeset to the current locale's codeset, unless 100*946379e7Schristosoverridden by a prior call to the 101*946379e7Schristos<b>bind_textdomain_codeset</b> function.</td></table> 102*946379e7Schristos 103*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 104*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 105*946379e7Schristos<tr valign="top" align="left"> 106*946379e7Schristos<td width="10%"></td><td width="90%"> 107*946379e7SchristosThe message catalog used by the functions is at the pathname 108*946379e7Schristos<i>dirname</i>/<i>locale</i>/<i>category</i>/<i>domainname</i>.mo. 109*946379e7SchristosHere <i>dirname</i> is the directory specified through 110*946379e7Schristos<b>bindtextdomain</b>. Its default is system and 111*946379e7Schristosconfiguration dependent; typically it is 112*946379e7Schristos<i>prefix</i>/share/locale, where <i>prefix</i> is the 113*946379e7Schristosinstallation prefix of the package. <i>locale</i> is the 114*946379e7Schristosname of the current locale facet; the GNU implementation 115*946379e7Schristosalso tries generalizations, such as the language name 116*946379e7Schristoswithout the territory name. <i>category</i> is 117*946379e7Schristos<b>LC_MESSAGES</b> for the <b>gettext</b> and 118*946379e7Schristos<b>dgettext</b> functions, or the argument passed to the 119*946379e7Schristos<b>dcgettext</b> function.</td></table> 120*946379e7Schristos 121*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 122*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 123*946379e7Schristos<tr valign="top" align="left"> 124*946379e7Schristos<td width="10%"></td><td width="90%"> 125*946379e7SchristosIf the <b>LANGUAGE</b> environment variable is set to a 126*946379e7Schristosnonempty value, and the locale is not the "C" 127*946379e7Schristoslocale, the value of <b>LANGUAGE</b> is assumed to contain a 128*946379e7Schristoscolon separated list of locale names. The functions will 129*946379e7Schristosattempt to look up a translation of <i>msgid</i> in each of 130*946379e7Schristosthe locales in turn. This is a GNU extension.</td></table> 131*946379e7Schristos 132*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 133*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 134*946379e7Schristos<tr valign="top" align="left"> 135*946379e7Schristos<td width="10%"></td><td width="90%"> 136*946379e7SchristosIn the "C" locale, or if none of the used catalogs 137*946379e7Schristoscontain a translation for <i>msgid</i>, the <b>gettext</b>, 138*946379e7Schristos<b>dgettext</b> and <b>dcgettext</b> functions return 139*946379e7Schristos<i>msgid</i>.</td></table> 140*946379e7Schristos<a name="RETURN VALUE"></a> 141*946379e7Schristos<h2>RETURN VALUE</h2> 142*946379e7Schristos 143*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 144*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 145*946379e7Schristos<tr valign="top" align="left"> 146*946379e7Schristos<td width="10%"></td><td width="90%"> 147*946379e7SchristosIf a translation was found in one of the specified catalogs, 148*946379e7Schristosit is converted to the locale's codeset and returned. The 149*946379e7Schristosresulting string is statically allocated and must not be 150*946379e7Schristosmodified or freed. Otherwise <i>msgid</i> is 151*946379e7Schristosreturned.</td></table> 152*946379e7Schristos<a name="ERRORS"></a> 153*946379e7Schristos<h2>ERRORS</h2> 154*946379e7Schristos 155*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 156*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 157*946379e7Schristos<tr valign="top" align="left"> 158*946379e7Schristos<td width="10%"></td><td width="90%"> 159*946379e7Schristos<b>errno</b> is not modified.</td></table> 160*946379e7Schristos<a name="BUGS"></a> 161*946379e7Schristos<h2>BUGS</h2> 162*946379e7Schristos 163*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 164*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 165*946379e7Schristos<tr valign="top" align="left"> 166*946379e7Schristos<td width="10%"></td><td width="90%"> 167*946379e7SchristosThe return type ought to be <b>const char *</b>, but is 168*946379e7Schristos<b>char *</b> to avoid warnings in C code predating ANSI 169*946379e7SchristosC.</td></table> 170*946379e7Schristos 171*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 172*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 173*946379e7Schristos<tr valign="top" align="left"> 174*946379e7Schristos<td width="10%"></td><td width="90%"> 175*946379e7SchristosWhen an empty string is used for <i>msgid</i>, the functions 176*946379e7Schristosmay return a nonempty string.</td></table> 177*946379e7Schristos<a name="SEE ALSO"></a> 178*946379e7Schristos<h2>SEE ALSO</h2> 179*946379e7Schristos 180*946379e7Schristos<table width="100%" border=0 rules="none" frame="void" 181*946379e7Schristos cols="2" cellspacing="0" cellpadding="0"> 182*946379e7Schristos<tr valign="top" align="left"> 183*946379e7Schristos<td width="10%"></td><td width="90%"> 184*946379e7Schristos<b>ngettext</b>(3), <b>dngettext</b>(3), 185*946379e7Schristos<b>dcngettext</b>(3), <b>setlocale</b>(3), 186*946379e7Schristos<b>textdomain</b>(3), <b>bindtextdomain</b>(3), 187*946379e7Schristos<b>bind_textdomain_codeset</b>(3), 188*946379e7Schristos<b>msgfmt</b>(1)</td></table> 189*946379e7Schristos<hr> 190*946379e7Schristos</body> 191*946379e7Schristos</html> 192