| blob | 057a7dccd00e3dba894ea37986e293be8521ff12 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T.
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH CATOPEN 3C "Dec 29, 1996"
48 .SH NAME
49 catopen, catclose \- open/close a message catalog
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <nl_types.h>
55 \fBnl_catd\fR \fBcatopen\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIoflag\fR);
56 .fi
58 .LP
59 .nf
60 \fBint\fR \fBcatclose\fR(\fBnl_catd\fR \fIcatd\fR);
61 .fi
63 .SH DESCRIPTION
64 .sp
65 .LP
66 The \fBcatopen()\fR function opens a message catalog and returns a message
67 catalog descriptor. \fIname\fR specifies the name of the message catalog to be
68 opened. If \fIname\fR contains a "/", then \fIname\fR specifies a complete
69 pathname for the message catalog; otherwise, the environment variable
70 \fBNLSPATH\fR is used and \fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES\fR
71 must exist. If \fBNLSPATH\fR does not exist in the environment, or if a message
72 catalog cannot be opened in any of the paths specified by \fBNLSPATH\fR, then
73 the default path \fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES\fR is used.
74 In the "C" locale, \fBcatopen()\fR will always succeed without checking the
75 default search path.
76 .sp
77 .LP
78 The names of message catalogs and their location in the filesystem can vary
79 from one system to another. Individual applications can choose to name or
80 locate message catalogs according to their own special needs. A mechanism is
81 therefore required to specify where the catalog resides.
82 .sp
83 .LP
84 The \fBNLSPATH\fR variable provides both the location of message catalogs, in
85 the form of a search path, and the naming conventions associated with message
86 catalog files. For example:
87 .sp
88 .in +2
89 .nf
90 NLSPATH=/nlslib/%L/%N.cat:/nlslib/%N/%L
91 .fi
92 .in -2
94 .sp
95 .LP
96 The metacharacter \fB%\fR introduces a substitution field, where \fB%L\fR
97 substitutes the current setting of either the \fBLANG\fR environment variable,
98 if the value of \fIoflag\fR is \fB0\fR, or the \fBLC_MESSAGES\fR category, if
99 the value of \fIoflag\fR is \fBNL_CAT_LOCALE\fR, and \fB%N\fR substitutes the
100 value of the \fIname\fR parameter passed to \fBcatopen()\fR. Thus, in the above
101 example, \fBcatopen()\fR will search in \fB/nlslib/$LANG/\fIname\fR.cat\fR, if
102 \fIoflag\fR is \fB0\fR, or in \fB/nlslib/{LC_MESSAGES}/\fIname\fR.cat\fR, if
103 \fIoflag\fR is \fBNL_CAT_LOCALE\fR.
104 .sp
105 .LP
106 The \fBNLSPATH\fR variable will normally be set up on a system wide basis (in
107 \fB/etc/profile\fR) and thus makes the location and naming conventions
108 associated with message catalogs transparent to both programs and users.
109 .sp
110 .LP
111 The full set of metacharacters is:
112 .sp
113 .ne 2
114 .na
115 \fB\fB%N\fR\fR
116 .ad
117 .RS 6n
118 The value of the name parameter passed to \fBcatopen()\fR.
119 .RE
121 .sp
122 .ne 2
123 .na
124 \fB\fB%L\fR\fR
125 .ad
126 .RS 6n
127 The value of \fBLANG\fR or \fBLC_MESSAGES\fR.
128 .RE
130 .sp
131 .ne 2
132 .na
133 \fB\fB%l\fR\fR
134 .ad
135 .RS 6n
136 The value of the \fIlanguage\fR element of \fBLANG\fR or \fBLC_MESSAGES\fR.
137 .RE
139 .sp
140 .ne 2
141 .na
142 \fB\fB%t\fR\fR
143 .ad
144 .RS 6n
145 The value of the \fIterritory\fR element of \fBLANG\fR or \fBLC_MESSAGES\fR.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fB%c\fR\fR
152 .ad
153 .RS 6n
154 The value of the \fIcodeset\fR element of \fBLANG\fR or \fBLC_MESSAGES\fR.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fB%%\fR\fR
161 .ad
162 .RS 6n
163 A single %.
164 .RE
166 .sp
167 .LP
168 The \fBLANG\fR environment variable provides the ability to specify the user's
169 requirements for native languages, local customs and character set, as an ASCII
170 string in the form
171 .sp
172 .in +2
173 .nf
174 LANG=language[_territory[.codeset]]
175 .fi
176 .in -2
178 .sp
179 .LP
180 A user who speaks German as it is spoken in Austria and has a terminal which
181 operates in ISO 8859/1 codeset, would want the setting of the LANG variable to
182 be
183 .sp
184 .in +2
185 .nf
186 LANG=De_A.88591
187 .fi
188 .in -2
190 .sp
191 .LP
192 With this setting it should be possible for that user to find any relevant
193 catalogs should they exist.
194 .sp
195 .LP
196 Should the \fBLANG\fR variable not be set, the value of \fBLC_MESSAGES\fR as
197 returned by \fBsetlocale()\fR is used. If this is \fINULL,\fR the default path
198 as defined in <\fBnl_types.h\fR> is used.
199 .sp
200 .LP
201 A message catalogue descriptor remains valid in a process until that process
202 closes it, or a successful call to one of the \fBexec\fR functions. A change in
203 the setting of the \fBLC_MESSAGES\fR category may invalidate existing open
204 catalogues.
205 .sp
206 .LP
207 If a file descriptor is used to implement message catalogue descriptors, the
208 \fBFD_CLOEXEC\fR flag will be set; see <\fBfcntl.h\fR>.
209 .sp
210 .LP
211 If the value of \fIoflag\fR argument is \fB0\fR, the \fBLANG\fR environment
212 variable is used to locate the catalogue without regard to the
213 \fBLC_MESSAGES\fR category. If the \fIoflag\fR argument is
214 \fBNL_CAT_LOCALE\fR, the \fBLC_MESSAGES\fR category is used to locate the
215 message catalogue.
216 .sp
217 .LP
218 The \fBcatclose()\fR function closes the message catalog identified by
219 \fIcatd\fR. If a file descriptor is used to implement the type \fBnl_catd\fR,
220 that file descriptor will be closed.
221 .SH RETURN VALUES
222 .sp
223 .LP
224 Upon successful completion, \fBcatopen()\fR returns a message catalog
225 descriptor for use on subsequent calls to \fBcatgets()\fR and
226 \fBcatclose()\fR. Otherwise it returns \fB(nl_catd) \(mi1\fR.
227 .sp
228 .LP
229 Upon successful completion, \fBcatclose()\fR returns 0. Otherwise it returns
230 \(mi1 and sets \fBerrno\fR to indicate the error.
231 .SH ERRORS
232 .sp
233 .LP
234 The \fBcatopen()\fR function may fail if:
235 .sp
236 .ne 2
237 .na
238 \fB\fBEACCES\fR\fR
239 .ad
240 .RS 16n
241 Search permission is denied for the component of the path prefix of the message
242 catalogue or read permission is denied for the message catalogue.
243 .RE
245 .sp
246 .ne 2
247 .na
248 \fB\fBEMFILE\fR\fR
249 .ad
250 .RS 16n
251 There are \fBOPEN_MAX\fR file descriptors currently open in the calling
252 process.
253 .RE
255 .sp
256 .ne 2
257 .na
258 \fB\fBENAMETOOLONG\fR\fR
259 .ad
260 .RS 16n
261 The length of the pathname of the message catalogue exceeds \fIPATH_MAX\fR, or
262 a pathname component is longer than \fINAME_MAX\fR.
263 .RE
265 .sp
266 .ne 2
267 .na
268 \fB\fBENAMETOOLONG\fR\fR
269 .ad
270 .RS 16n
271 Pathname resolution of a symbolic link produced an intermediate result whose
272 length exceeds \fIPATH_MAX\fR.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fBENFILE\fR\fR
279 .ad
280 .RS 16n
281 Too many files are currently open in the system.
282 .RE
284 .sp
285 .ne 2
286 .na
287 \fB\fBENOENT\fR\fR
288 .ad
289 .RS 16n
290 The message catalogue does not exist or the \fIname\fR argument points to an
291 empty string.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBENOMEM\fR\fR
298 .ad
299 .RS 16n
300 Insufficient storage space is available.
301 .RE
303 .sp
304 .ne 2
305 .na
306 \fB\fBENOTDIR\fR\fR
307 .ad
308 .RS 16n
309 A component of the path prefix of the message catalogue is not a directory.
310 .RE
312 .sp
313 .LP
314 The \fBcatclose()\fR function may fail if:
315 .sp
316 .ne 2
317 .na
318 \fB\fBEBADF\fR\fR
319 .ad
320 .RS 9n
321 The catalogue descriptor is not valid.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBEINTR\fR\fR
328 .ad
329 .RS 9n
330 The \fBcatclose()\fR function was interrupted by a signal.
331 .RE
333 .SH USAGE
334 .sp
335 .LP
336 The \fBcatopen()\fR and \fBcatclose()\fR functions can be used safely in
337 multithreaded applications, as long as \fBsetlocale\fR(3C) is not being called
338 to change the locale.
339 .SH ATTRIBUTES
340 .sp
341 .LP
342 See \fBattributes\fR(5) for descriptions of the following attributes:
343 .sp
345 .sp
346 .TS
347 box;
348 c | c
349 l | l .
350 ATTRIBUTE TYPE ATTRIBUTE VALUE
351 _
352 Interface Stability Standard
353 _
354 MT-Level MT-Safe
355 .TE
357 .SH SEE ALSO
358 .sp
359 .LP
360 \fBgencat\fR(1), \fBcatgets\fR(3C), \fBgettext\fR(3C), \fBnl_types.h\fR(3HEAD),
361 \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5)