dngettext(3c)

1gettext(3C)              Standard C Library Functions              gettext(3C)
2
3
4

NAME

6       gettext,  dgettext, dcgettext, ngettext, dngettext, dcngettext, textdo‐
7       main, bindtextdomain, bind_textdomain_codeset - message handling  func‐
8       tions
9

SYNOPSIS

11   Solaris and GNU-compatible
12       #include <libintl.h>
13
14       char *gettext(const char *msgid);
15
16
17       char *dgettext(const char *domainname, const char *msgid);
18
19
20       char *textdomain(const char *domainname);
21
22
23       char *bindtextdomain(const char *domainname, const char *dirname);
24
25
26       #include <libintl.h>
27       #include <locale.h>
28
29       char *dcgettext(const char *domainname, const char *msgid,
30            int category);
31
32
33   GNU-compatible
34       #include <libintl.h>
35
36       char *ngettext(const char *msgid1, const char *msgid2,
37            unsigned long int n);
38
39
40       char *dngettext(const char *domainname, const char *msgid1,
41            const char *msgid2, unsigned long int n);
42
43
44       char *bind_textdomain_codeset(const char *domainname,
45            const char *codeset);
46
47
48       extern int _nl_msg_cat_cntr;
49       extern int *_nl_domain_bindings;
50
51
52       #include <libintl.h>
53       #include <locale.h>
54
55       char *dcngettext(const char *domainname, const char *msgid1,
56            const char *msgid2, unsigned long int n, int category);
57
58

DESCRIPTION

60       The   gettext(),  dgettext(),  and  dcgettext()  functions  attempt  to
61       retrieve a target string based on the specified msgid  argument  within
62       the  context of a specific domain and the current locale. The length of
63       strings returned by gettext(),  dgettext(), and dcgettext() is undeter‐
64       mined until the function is called. The msgid argument is a null-termi‐
65       nated string.
66
67
68       The ngettext(), dngettext(), and dcngettext() functions are  equivalent
69       to gettext(), dgettext(), and dcgettext(), respectively, except for the
70       handling of plural forms.  These functions work only with  GNU-compati‐
71       ble  message catalogues.  The ngettext(), dngettext(), and dcngettext()
72       functions search for the message string using the  msgid1  argument  as
73       the key and the n argument to determine the plural form.  If no message
74       catalogues are found, msgid1 is returned if n == 1, otherwise msgid2 is
75       returned.
76
77
78       The NLSPATH environment variable (see environ(5)) is searched first for
79       the location of the  LC_MESSAGES catalogue. The setting of the  LC_MES‐
80       SAGES  category  of  the  current  locale determines the locale used by
81       gettext() and dgettext() for string retrieval.  The  category  argument
82       determines  the  locale  used by dcgettext(). If NLSPATH is not defined
83       and the current locale is "C", gettext(), dgettext(),  and  dcgettext()
84       simply  return  the message string that was passed.  In a locale  other
85       than "C", if NLSPATH is not defined or if a message  catalogue  is  not
86       found  in  any  of  the  components  specified by NLSPATH, the routines
87       search for the message catalogue using the scheme described in the fol‐
88       lowing paragraph.
89
90
91       The LANGUAGE environment variable is examined to determine the GNU-com‐
92       patible message catalogues to be used. The value of LANGUAGE is a  list
93       of  locale  names separated by a colon (':') character.  If LANGUAGE is
94       defined, each locale name is tried in the specified order and if a GNU-
95       compatible  message  catalogue is found, the message is returned.  If a
96       GNU-compatible message catalogue is found but failed to find  a  corre‐
97       sponding  msgid, the msgid string is return. If LANGUAGE is not defined
98       or if a Solaris message catalogue is found or no GNU-compatible message
99       catalogue  is found in processing LANGUAGE, the pathname used to locate
100       the message catalogue is  dirname/locale/category/domainname.mo,  where
101       dirname  is  the  directory  specified by bindtextdomain(), locale is a
102       locale name, and category is either  LC_MESSAGES  if  gettext(),  dget‐
103       text(),  ngettext(), or dngettext() is called, or LC_XXX where the name
104       is the same as the locale category name specified by the category argu‐
105       ment to dcgettext() or dcngettext().
106
107
108       For  gettext() and ngettext(), the domain used is set by the last valid
109       call to textdomain(). If a valid call  to  textdomain()  has  not  been
110       made, the default domain  (called messages) is used.
111
112
113       For  dgettext(), dcgettext(), dngettext(), and dcngettext(), the domain
114       used is specified by the domainname argument. The  domainname  argument
115       is  equivalent  in  syntax  and  meaning  to the domainname argument to
116       textdomain(), except that the selection of the domain is valid only for
117       the  duration  of  the dgettext(), dcgettext(), dngettext(), or dcnget‐
118       text() function call.
119
120
121       The textdomain() function sets or  queries  the  name  of  the  current
122       domain of the active  LC_MESSAGES locale category. The domainname argu‐
123       ment is a null-terminated string that can contain only  the  characters
124       allowed in legal filenames.
125
126
127       The  domainname  argument is the unique name of a domain on the system.
128       If there are multiple versions of the same domain on one system, names‐
129       pace  collisions  can be avoided by using  bindtextdomain(). If textdo‐
130       main() is not called, a default domain  is  selected.  The  setting  of
131       domain made by the last valid call to textdomain() remains valid across
132       subsequent calls to  setlocale(3C), and gettext().
133
134
135       The  domainname argument is applied to the currently active LC_MESSAGES
136       locale.
137
138
139       The  current setting of the domain can be queried without affecting the
140       current state of the domain by calling textdomain() with domainname set
141       to  the  null pointer. Calling textdomain() with a  domainname argument
142       of a null string sets the domain to the default domain (messages).
143
144
145       The bindtextdomain() function binds the path predicate  for  a  message
146       domain domainname to the value contained in dirname. If domainname is a
147       non-empty string and has not been  bound  previously,  bindtextdomain()
148       binds  domainname with  dirname.
149
150
151       If   domainname  is  a  non-empty string and has been bound previously,
152       bindtextdomain() replaces the old binding with   dirname.  The  dirname
153       argument  can  be  an absolute or relative pathname being resolved when
154       gettext(), dgettext(), or dcgettext() are called. If  domainname  is  a
155       null  pointer  or an empty string,  bindtextdomain() returns NULL. User
156       defined domain names cannot begin with the string  SYS_.  Domain  names
157       beginning with this string are reserved for system use.
158
159
160       The  bind_textdomain_codeset() function can be used to specify the out‐
161       put codeset for message catalogues for domain domainname.  The  codeset
162       argument  must  be  a  valid  codeset  name  that  can  be used for the
163       iconv_open(3C) function, or a null pointer. If the codeset argument  is
164       the  null  pointer,  bind_textdomain_codeset()  returns  the  currently
165       selected codeset for the domain with the name domainname.  It returns a
166       null  pointer  if a codeset has not yet been selected. The bind_textdo‐
167       main_codeset() function can be used multiple times.  If  used  multiple
168       times  with  the same domainname argument, the later call overrides the
169       settings made by the earlier one. The  bind_textdomain_codeset()  func‐
170       tion  returns a pointer to a string containing the name of the selected
171       codeset. The string is allocated internally in the  function  and  must
172       not be changed by the user.
173
174
175       The  external  variables  _nl_msg_cat_cntr  and _nl_domain_bindings are
176       provided for the compatibility with the GNU gettext() implementation.
177

RETURN VALUES

179       The gettext(), dgettext(), and dcgettext() functions return the message
180       string if the search succeeds. Otherwise they return the msgid string.
181
182
183       The ngettext(), dngettext(), and dcngettext() functions return the mes‐
184       sage string if the search succeeds.  If the  search  fails,  msgid1  is
185       returned if n == 1. Otherwise msgid2 is returned.
186
187
188       The  individual bytes of the string returned by gettext(),  dgettext(),
189       dcgettext(), ngettext(), dngettext(), or dcngettext() can  contain  any
190       value  other than NULL. If msgid is a null pointer, the return value is
191       undefined. The string returned must not be modified by the program  and
192       can be invalidated by a subsequent call to bind_textdomain_codeset() or
193       setlocale(3C). If the  domainname argument to   dgettext(),dcgettext(),
194       dngettext(),  or  dcngettext()  is  a null pointer, the the domain cur‐
195       rently bound by textdomain() is used.
196
197
198       The normal return value from textdomain() is a pointer to a string con‐
199       taining  the  current  setting  of  the domain. If domainname is a null
200       pointer, textdomain() returns a pointer to the  string  containing  the
201       current  domain.  If textdomain() was not previously called and domain‐
202       name is a null string, the name of the default domain is returned.  The
203       name  of  the default domain is messages. If textdomain() fails, a null
204       pointer is returned.
205
206
207       The return value from bindtextdomain() is a null-terminated string con‐
208       taining  dirname or the directory binding associated with domainname if
209       dirname is NULL. If no binding is found, the default  return  value  is
210       /usr/lib/locale.  If   domainname is a null pointer or an empty string,
211       bindtextdomain() takes no action and returns a null pointer. The string
212       returned must not be modified by the caller. If bindtextdomain() fails,
213       a null pointer is returned.
214

USAGE

216       These functions impose no limit on  message  length.  However,  a  text
217       domainname is limited to TEXTDOMAINMAX (256) bytes.
218
219
220       The   gettext(),   dgettext(),  dcgettext(),  ngettext(),  dngettext(),
221       dcngettext(), textdomain(), and bindtextdomain() functions can be  used
222       safely  in  multithreaded applications, as long as setlocale(3C) is not
223       being called to change the locale.
224
225
226       The gettext(), dgettext(), dcgettext(), textdomain(),  and  bindtextdo‐
227       main() functions work with both Solaris message catalogues and GNU-com‐
228       patible message catalogues.  The ngettext(), dngettext(), dcngettext(),
229       and  bind_textdomain_codeset()  functions work only with GNU-compatible
230       message catalogues.  See msgfmt(1) for information about  Solaris  mes‐
231       sage catalogues and GNU-compatible message catalogues.
232

FILES

234       /usr/lib/locale
235
236           default path predicate for message domain files
237
238
239       /usr/lib/locale/locale/LC_MESSAGES/domainname.mo
240
241           system  default location for file containing messages for  language
242           locale and domainname
243
244
245       /usr/lib/locale/locale/LC_XXX/domainname.mo
246
247           system default location for file containing messages for   language
248           locale  and  domainname  for  dcgettext()  calls  where  LC_XXX  is
249           LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, or  LC_MES‐
250           SAGES
251
252
253       dirname/locale/LC_MESSAGES/domainname.mo
254
255           location  for  file  containing  messages for domain domainname and
256           path predicate dirname after a successful call to bindtextdomain()
257
258
259       dirname/locale/LC_XXX/domainname.mo
260
261           location for files containing messages for domain domainname,  lan‐
262           guage locale, and path predicate dirname after a successful call to
263           bindtextdomain() for dcgettext()  calls  where  LC_XXX  is  one  of
264           LC_CTYPE,  LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, or LC_MES‐
265           SAGES
266
267

ATTRIBUTES

269       See attributes(5) for descriptions of the following attributes:
270
271
272
273
274       ┌─────────────────────────────┬─────────────────────────────┐
275       │ATTRIBUTE TYPE               │ATTRIBUTE VALUE              │
276       ├─────────────────────────────┼─────────────────────────────┤
277       │Interface Stability          │See below.                   │
278       ├─────────────────────────────┼─────────────────────────────┤
279       │MT-Level                     │Safe with exceptions         │
280       └─────────────────────────────┴─────────────────────────────┘
281
282
283       The external variables  _nl_msg_cat_cntr  and  _nl_domain_bindings  are
284       Uncommitted.
285