| blob | 4f08aee4447888c808727015147b38f38e64e143 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH GETTEXT 3C "April 9, 2016"
7 .SH NAME
8 gettext, dgettext, dcgettext, ngettext, dngettext, dcngettext, textdomain,
9 bindtextdomain, bind_textdomain_codeset \- message handling functions
10 .SH SYNOPSIS
11 .SS "Solaris and GNU-compatible"
12 .LP
13 .nf
14 #include <libintl.h>
16 \fBchar *\fR\fBgettext\fR(\fBconst char *\fR\fImsgid\fR);
17 .fi
19 .LP
20 .nf
21 \fBchar *\fR\fBdgettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid\fR);
22 .fi
24 .LP
25 .nf
26 \fBchar *\fR\fBtextdomain\fR(\fBconst char *\fR\fIdomainname\fR);
27 .fi
29 .LP
30 .nf
31 \fBchar *\fR\fBbindtextdomain\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fIdirname\fR);
32 .fi
34 .LP
35 .nf
36 #include <libintl.h>
37 #include <locale.h>
39 \fBchar *\fR\fBdcgettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid\fR,
40 \fBint\fR \fIcategory\fR);
41 .fi
43 .SS "GNU-compatible"
44 .LP
45 .nf
46 #include <libintl.h>
48 \fBchar *\fR\fBngettext\fR(\fBconst char *\fR\fImsgid1\fR, \fBconst char *\fR\fImsgid2\fR,
49 \fBunsigned long int\fR \fIn\fR);
50 .fi
52 .LP
53 .nf
54 \fBchar *\fR\fBdngettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid1\fR,
55 \fBconst char *\fR\fImsgid2\fR, \fBunsigned long int\fR \fIn\fR);
56 .fi
58 .LP
59 .nf
60 \fBchar *\fR\fBbind_textdomain_codeset\fR(\fBconst char *\fR\fIdomainname\fR,
61 \fBconst char *\fR\fIcodeset\fR);
62 .fi
64 .LP
65 .nf
66 extern int _nl_msg_cat_cntr;
67 extern int *_nl_domain_bindings;
68 .fi
70 .LP
71 .nf
72 #include <libintl.h>
73 #include <locale.h>
75 \fBchar *\fR\fBdcngettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid1\fR,
76 \fBconst char *\fR\fImsgid2\fR, \fBunsigned long int\fR \fIn\fR, \fBint\fR \fIcategory\fR);
77 .fi
79 .SH DESCRIPTION
80 .LP
81 The \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR functions attempt
82 to retrieve a target string based on the specified \fImsgid\fR argument within
83 the context of a specific domain and the current locale. The length of strings
84 returned by \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR is
85 undetermined until the function is called. The \fImsgid\fR argument is a
86 null-terminated string.
87 .sp
88 .LP
89 The \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR functions are
90 equivalent to \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR,
91 respectively, except for the handling of plural forms. These functions work
92 only with GNU-compatible message catalogues. The \fBngettext()\fR,
93 \fBdngettext()\fR, and \fBdcngettext()\fR functions search for the message
94 string using the \fImsgid1\fR argument as the key and the \fIn\fR argument to
95 determine the plural form. If no message catalogues are found, \fImsgid1\fR is
96 returned if \fIn\fR == 1, otherwise \fImsgid2\fR is returned.
97 .sp
98 .LP
99 The \fBNLSPATH\fR environment variable (see \fBenviron\fR(5)) is searched first
100 for the location of the \fBLC_MESSAGES\fR catalogue. The setting of the
101 \fBLC_MESSAGES\fR category of the current locale determines the locale used by
102 \fBgettext()\fR and \fBdgettext()\fR for string retrieval. The \fIcategory\fR
103 argument determines the locale used by \fBdcgettext(\|).\fR If \fBNLSPATH\fR is
104 not defined and the current locale is "C", \fBgettext()\fR, \fBdgettext()\fR,
105 and \fBdcgettext()\fR simply return the message string that was passed. In a
106 locale other than "C", if \fBNLSPATH\fR is not defined or if a message
107 catalogue is not found in any of the components specified by \fBNLSPATH\fR, the
108 routines search for the message catalogue using the scheme described in the
109 following paragraph.
110 .sp
111 .LP
112 The \fBLANGUAGE\fR environment variable is examined to determine the
113 GNU-compatible message catalogues to be used. The value of \fBLANGUAGE\fR is a
114 list of locale names separated by a colon (':') character. If \fBLANGUAGE\fR
115 is defined, each locale name is tried in the specified order and if a
116 GNU-compatible message catalogue is found, the message is returned. If a
117 GNU-compatible message catalogue is found but failed to find a corresponding
118 \fImsgid\fR, the \fImsgid\fR string is return. If \fBLANGUAGE\fR is not defined
119 or if a Solaris message catalogue is found or no GNU-compatible message
120 catalogue is found in processing \fBLANGUAGE\fR, the pathname used to locate
121 the message catalogue is
122 \fIdirname\fR/\fIlocale\fR/\fIcategory\fR/\fIdomainname\fR.mo, where
123 \fIdirname\fR is the directory specified by \fBbindtextdomain()\fR,
124 \fIlocale\fR is a locale name, and \fIcategory\fR is either \fBLC_MESSAGES\fR
125 if \fBgettext()\fR, \fBdgettext()\fR, \fBngettext()\fR, or \fBdngettext()\fR is
126 called, or \fBLC_XXX\fR where the name is the same as the locale category name
127 specified by the \fIcategory\fR argument to \fBdcgettext()\fR or
128 \fBdcngettext()\fR.
129 .sp
130 .LP
131 For \fBgettext()\fR and \fBngettext()\fR, the domain used is set by the last
132 valid call to \fBtextdomain()\fR. If a valid call to \fBtextdomain()\fR has not
133 been made, the default domain (called \fBmessages\fR) is used.
134 .sp
135 .LP
136 For \fBdgettext()\fR, \fBdcgettext()\fR, \fBdngettext()\fR, and
137 \fBdcngettext()\fR, the domain used is specified by the \fIdomainname\fR
138 argument. The \fIdomainname\fR argument is equivalent in syntax and meaning to
139 the \fIdomainname\fR argument to \fBtextdomain()\fR, except that the selection
140 of the domain is valid only for the duration of the \fBdgettext()\fR,
141 \fBdcgettext()\fR, \fBdngettext()\fR, or \fBdcngettext()\fR function call.
142 .sp
143 .LP
144 The \fBtextdomain()\fR function sets or queries the name of the current domain
145 of the active \fBLC_MESSAGES\fR locale category. The \fIdomainname\fR argument
146 is a null-terminated string that can contain only the characters allowed in
147 legal filenames.
148 .sp
149 .LP
150 The \fIdomainname\fR argument is the unique name of a domain on the system. If
151 there are multiple versions of the same domain on one system, namespace
152 collisions can be avoided by using \fBbindtextdomain()\fR. If
153 \fBtextdomain()\fR is not called, a default domain is selected. The setting of
154 domain made by the last valid call to \fBtextdomain()\fR remains valid across
155 subsequent calls to \fBsetlocale\fR(3C), and \fBgettext()\fR.
156 .sp
157 .LP
158 The \fIdomainname\fR argument is applied to the currently active
159 \fBLC_MESSAGES\fR locale.
160 .sp
161 .LP
162 The current setting of the domain can be queried without affecting the current
163 state of the domain by calling \fBtextdomain()\fR with \fIdomainname\fR set to
164 the null pointer. Calling \fBtextdomain()\fR with a \fIdomainname\fR argument
165 of a null string sets the domain to the default domain (\fBmessages\fR).
166 .sp
167 .LP
168 The \fBbindtextdomain()\fR function binds the path predicate for a message
169 domain \fIdomainname\fR to the value contained in \fIdirname\fR. If
170 \fIdomainname\fR is a non-empty string and has not been bound previously,
171 \fBbindtextdomain()\fR binds \fIdomainname\fR with \fIdirname\fR.
172 .sp
173 .LP
174 If \fIdomainname\fR is a non-empty string and has been bound previously,
175 \fBbindtextdomain()\fR replaces the old binding with \fIdirname\fR. The
176 \fIdirname\fR argument can be an absolute or relative pathname being resolved
177 when \fBgettext()\fR, \fBdgettext()\fR, or \fBdcgettext()\fR are called. If
178 \fIdomainname\fR is a null pointer or an empty string, \fBbindtextdomain()\fR
179 returns \fINULL.\fR User defined domain names cannot begin with the string
180 \fBSYS_\fR. Domain names beginning with this string are reserved for system
181 use.
182 .sp
183 .LP
184 The \fBbind_textdomain_codeset()\fR function can be used to specify the output
185 codeset for message catalogues for domain \fIdomainname\fR. The \fIcodeset\fR
186 argument must be a valid codeset name that can be used for the
187 \fBiconv_open\fR(3C) function, or a null pointer. If the \fIcodeset\fR argument
188 is the null pointer, \fBbind_textdomain_codeset()\fR returns the currently
189 selected codeset for the domain with the name \fIdomainname\fR. It returns a
190 null pointer if a codeset has not yet been selected. The
191 \fBbind_textdomain_codeset()\fR function can be used multiple times. If used
192 multiple times with the same \fIdomainname\fR argument, the later call
193 overrides the settings made by the earlier one. The
194 \fBbind_textdomain_codeset()\fR function returns a pointer to a string
195 containing the name of the selected codeset. The string is allocated internally
196 in the function and must not be changed by the user.
197 .sp
198 .LP
199 The external variables \fB_nl_msg_cat_cntr\fR and \fB_nl_domain_bindings\fR are
200 provided for the compatibility with the GNU \fBgettext()\fR implementation.
201 .SH RETURN VALUES
202 .LP
203 The \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR functions return
204 the message string if the search succeeds. Otherwise they return the
205 \fImsgid\fR string.
206 .sp
207 .LP
208 The \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR functions
209 return the message string if the search succeeds. If the search fails,
210 \fImsgid1\fR is returned if \fIn\fR == 1. Otherwise \fImsgid2\fR is returned.
211 .sp
212 .LP
213 The individual bytes of the string returned by \fBgettext()\fR,
214 \fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR, \fBdngettext()\fR, or
215 \fBdcngettext()\fR can contain any value other than \fINULL\fR. If \fImsgid\fR
216 is a null pointer, the return value is undefined. The string returned must not
217 be modified by the program and can be invalidated by a subsequent call to
218 \fBbind_textdomain_codeset()\fR or \fBsetlocale\fR(3C). If the
219 \fIdomainname\fR argument to \fBdgettext()\fR,\fBdcgettext()\fR,
220 \fBdngettext()\fR, or \fBdcngettext()\fR is a null pointer, the domain
221 currently bound by \fBtextdomain()\fR is used.
222 .sp
223 .LP
224 The normal return value from \fBtextdomain()\fR is a pointer to a string
225 containing the current setting of the domain. If \fIdomainname\fR is a null
226 pointer, \fBtextdomain()\fR returns a pointer to the string containing the
227 current domain. If \fBtextdomain()\fR was not previously called and
228 \fIdomainname\fR is a null string, the name of the default domain is returned.
229 The name of the default domain is \fBmessages\fR. If \fBtextdomain()\fR fails,
230 a null pointer is returned.
231 .sp
232 .LP
233 The return value from \fBbindtextdomain()\fR is a null-terminated string
234 containing \fIdirname\fR or the directory binding associated with
235 \fIdomainname\fR if \fIdirname\fR is \fINULL.\fR If no binding is found, the
236 default return value is \fB/usr/lib/locale\fR. If \fIdomainname\fR is a null
237 pointer or an empty string, \fBbindtextdomain()\fR takes no action and returns
238 a null pointer. The string returned must not be modified by the caller. If
239 \fBbindtextdomain()\fR fails, a null pointer is returned.
240 .SH USAGE
241 .LP
242 These functions impose no limit on message length. However, a text
243 \fIdomainname\fR is limited to \fBTEXTDOMAINMAX\fR (256) bytes.
244 .sp
245 .LP
246 The \fBgettext()\fR, \fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR,
247 \fBdngettext()\fR, \fBdcngettext()\fR, \fBtextdomain()\fR, and
248 \fBbindtextdomain()\fR functions can be used safely in multithreaded
249 applications, as long as \fBsetlocale\fR(3C) is not being called to change the
250 locale.
251 .sp
252 .LP
253 The \fBgettext()\fR, \fBdgettext()\fR, \fBdcgettext()\fR, \fBtextdomain()\fR,
254 and \fBbindtextdomain()\fR functions work with both Solaris message catalogues
255 and GNU-compatible message catalogues. The \fBngettext()\fR,
256 \fBdngettext()\fR, \fBdcngettext()\fR, and \fBbind_textdomain_codeset()\fR
257 functions work only with GNU-compatible message catalogues. See
258 \fBmsgfmt\fR(1) for information about Solaris message catalogues and
259 GNU-compatible message catalogues.
260 .SH FILES
261 .ne 2
262 .na
263 \fB\fB/usr/lib/locale\fR\fR
264 .ad
265 .sp .6
266 .RS 4n
267 default path predicate for message domain files
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES/\fR\fIdomainname\fR\fB\&.m
274 o\fR\fR
275 .ad
276 .sp .6
277 .RS 4n
278 system default location for file containing messages for language
279 \fIlocale\fR and \fIdomainname\fR
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_XXX/\fR\fIdomainname\fR\fB\&.mo\fR\fR
286 .ad
287 .sp .6
288 .RS 4n
289 system default location for file containing messages for language
290 \fIlocale\fR and \fIdomainname\fR for \fBdcgettext()\fR calls where
291 \fBLC_XXX\fR is \fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR,
292 \fBLC_COLLATE\fR, \fBLC_MONETARY\fR, or \fBLC_MESSAGES\fR
293 .RE
295 .sp
296 .ne 2
297 .na
298 \fB\fB\fR\fIdirname\fR\fB/\fR\fIlocale\fR\fB/LC_MESSAGES/\fR\fIdomainname\fR\fB
299 \&.mo\fR\fR
300 .ad
301 .sp .6
302 .RS 4n
303 location for file containing messages for domain \fIdomainname\fR and path
304 predicate \fIdirname\fR after a successful call to \fBbindtextdomain()\fR
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fB\fR\fIdirname\fR\fB/\fR\fIlocale\fR\fB/LC_XXX/\fR\fIdomainname\fR\fB\&.mo
311 \fR\fR
312 .ad
313 .sp .6
314 .RS 4n
315 location for files containing messages for domain \fIdomainname,\fR language
316 \fIlocale,\fR and path predicate \fIdirname\fR after a successful call to
317 \fBbindtextdomain()\fR for \fBdcgettext()\fR calls where \fBLC_XXX\fR is one of
318 \fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR, \fBLC_COLLATE\fR,
319 \fBLC_MONETARY\fR, or \fBLC_MESSAGES\fR
320 .RE
322 .SH ATTRIBUTES
323 .LP
324 See \fBattributes\fR(5) for descriptions of the following attributes:
325 .sp
327 .sp
328 .TS
329 box;
330 c | c
331 l | l .
332 ATTRIBUTE TYPE ATTRIBUTE VALUE
333 _
334 Interface Stability See below.
335 _
336 MT-Level Safe with exceptions
337 .TE
339 .sp
340 .LP
341 The external variables \fB_nl_msg_cat_cntr\fR and \fB_nl_domain_bindings\fR are
342 Uncommitted.
343 .SH SEE ALSO
344 .LP
345 \fBmsgfmt\fR(1), \fBxgettext\fR(1), \fBiconv_open\fR(3C),
346 \fBlibintl.h\fR(3HEAD), \fBsetlocale\fR(3C), \fBattributes\fR(5),
347 \fBenviron\fR(5)