]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk> |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze <joey@infodrom.org> | |
26 | .\" Modified 2001-12-14 aeb | |
27 | .\" | |
460495ca | 28 | .TH CATOPEN 3 2015-08-08 "GNU" "Linux Programmer's Manual" |
fea681da MK |
29 | .SH NAME |
30 | catopen, catclose \- open/close a message catalog | |
31 | .SH SYNOPSIS | |
32 | .B #include <nl_types.h> | |
68e4db0a | 33 | .PP |
fea681da | 34 | .BI "nl_catd catopen(const char *" name ", int " flag ); |
dbfe9c70 | 35 | .PP |
fea681da MK |
36 | .BI "int catclose(nl_catd " catalog ); |
37 | .SH DESCRIPTION | |
38 | The function | |
63aa9df0 | 39 | .BR catopen () |
fea681da | 40 | opens a message catalog and returns a catalog descriptor. |
c13182ef MK |
41 | The descriptor remains valid until |
42 | .BR catclose () | |
43 | or | |
fb186734 | 44 | .BR execve (2). |
b0b89919 | 45 | If a file descriptor is used to implement catalog descriptors, |
1274071a MK |
46 | then the |
47 | .B FD_CLOEXEC | |
48 | flag will be set. | |
dd3568a1 | 49 | .PP |
fea681da MK |
50 | The argument |
51 | .I name | |
52 | specifies the name of the message catalog to be opened. | |
53 | If | |
54 | .I name | |
8830fd64 | 55 | specifies an absolute path (i.e., contains a \(aq/\(aq), |
fea681da MK |
56 | then |
57 | .I name | |
58 | specifies a pathname for the message catalog. | |
59 | Otherwise, the environment variable | |
60 | .B NLSPATH | |
61 | is used with | |
62 | .I name | |
63 | substituted for | |
64 | .B %N | |
65 | (see | |
66 | .BR locale (7)). | |
67 | It is unspecified whether | |
68 | .B NLSPATH | |
69 | will be used when the process has root privileges. | |
70 | If | |
71 | .B NLSPATH | |
72 | does not exist in the environment, | |
73 | or if a message catalog cannot be opened | |
74 | in any of the paths specified by it, | |
75 | then an implementation defined path is used. | |
76 | This latter default path may depend on the | |
77 | .B LC_MESSAGES | |
78 | locale setting when the | |
79 | .I flag | |
80 | argument is | |
81 | .B NL_CAT_LOCALE | |
82 | and on the | |
83 | .B LANG | |
84 | environment variable when the | |
85 | .I flag | |
86 | argument is 0. | |
2f0af33b MK |
87 | Changing the |
88 | .B LC_MESSAGES | |
89 | part of the locale may invalidate | |
fea681da | 90 | open catalog descriptors. |
dd3568a1 | 91 | .PP |
fea681da MK |
92 | The |
93 | .I flag | |
94 | argument to | |
63aa9df0 | 95 | .BR catopen () |
fea681da MK |
96 | is used to indicate the source for the language to use. |
97 | If it is set to | |
b0b89919 | 98 | .BR NL_CAT_LOCALE , |
fea681da MK |
99 | then it will use the current locale setting for |
100 | .BR LC_MESSAGES . | |
2b9b829d | 101 | Otherwise, it will use the |
fea681da MK |
102 | .B LANG |
103 | environment variable. | |
dd3568a1 | 104 | .PP |
fea681da | 105 | The function |
63aa9df0 | 106 | .BR catclose () |
fea681da MK |
107 | closes the message catalog identified by |
108 | .IR catalog . | |
109 | It invalidates any subsequent references to the message catalog | |
110 | defined by | |
111 | .IR catalog . | |
47297adb | 112 | .SH RETURN VALUE |
fea681da | 113 | The function |
63aa9df0 | 114 | .BR catopen () |
fea681da MK |
115 | returns a message catalog descriptor of type |
116 | .I nl_catd | |
117 | on success. | |
c9942389 MK |
118 | On failure, it returns |
119 | .IR "(nl_catd)\ \-1" | |
fea681da | 120 | and sets |
1bf89c60 | 121 | .I errno |
c13182ef MK |
122 | to indicate the error. |
123 | The possible error values include all | |
fea681da | 124 | possible values for the |
fb186734 | 125 | .BR open (2) |
fea681da | 126 | call. |
dd3568a1 | 127 | .PP |
fea681da | 128 | The function |
63aa9df0 | 129 | .BR catclose () |
fea681da MK |
130 | returns 0 on success, or \-1 on failure. |
131 | .SH ENVIRONMENT | |
132 | .TP | |
133 | .B LC_MESSAGES | |
2f0af33b MK |
134 | May be the source of the |
135 | .B LC_MESSAGES | |
136 | locale setting, and thus | |
fea681da MK |
137 | determine the language to use if |
138 | .I flag | |
139 | is set to | |
140 | .BR NL_CAT_LOCALE . | |
141 | .TP | |
142 | .B LANG | |
143 | The language to use if | |
144 | .I flag | |
145 | is 0. | |
0af646b2 PH |
146 | .SH ATTRIBUTES |
147 | For an explanation of the terms used in this section, see | |
148 | .BR attributes (7). | |
149 | .TS | |
150 | allbox; | |
151 | lb lb lb | |
152 | l l l. | |
153 | Interface Attribute Value | |
154 | T{ | |
155 | .BR catopen () | |
156 | T} Thread safety MT-Safe env | |
157 | T{ | |
158 | .BR catclose () | |
159 | T} Thread safety MT-Safe | |
160 | .TE | |
47297adb | 161 | .SH CONFORMING TO |
493d9724 | 162 | POSIX.1-2001, POSIX.1-2008. |
2b2581ee MK |
163 | .\" In XPG 1987, Vol. 3 it says: |
164 | .\" .I "The flag argument of catopen is reserved for future use" | |
165 | .\" .IR "and should be set to 0" . | |
3ef5eb12 MK |
166 | .\" |
167 | .\" It is unclear what the source was for the constants | |
168 | .\" .B MCLoadBySet | |
169 | .\" and | |
170 | .\" .B MCLoadAll | |
171 | .\" (see below). | |
fea681da | 172 | .SH NOTES |
493d9724 | 173 | The above is the POSIX.1 description. |
2f0af33b MK |
174 | The glibc value for |
175 | .B NL_CAT_LOCALE | |
176 | is 1. | |
3ef5eb12 MK |
177 | .\" (Compare |
178 | .\" .B MCLoadAll | |
179 | .\" below.) | |
fea681da MK |
180 | The default path varies, but usually looks at a number of places below |
181 | .IR /usr/share/locale . | |
3ef5eb12 MK |
182 | .\" .SS Linux notes |
183 | .\" These functions are available for Linux since libc 4.4.4c. | |
184 | .\" In the case of linux libc4 and libc5, the catalog descriptor | |
185 | .\" .I nl_catd | |
186 | .\" is a | |
187 | .\" .BR mmap (2)'ed | |
188 | .\" area of memory and not a file descriptor. | |
189 | .\" The | |
190 | .\" .I flag | |
191 | .\" argument to | |
192 | .\" .BR catopen () | |
193 | .\" should be either | |
194 | .\" .B MCLoadBySet | |
195 | .\" (=0) or | |
196 | .\" .B MCLoadAll | |
197 | .\" (=1). | |
198 | .\" The former value indicates that a set from the catalog is to be | |
199 | .\" loaded when needed, whereas the latter causes the initial call to | |
200 | .\" .BR catopen () | |
201 | .\" to load the entire catalog into memory. | |
202 | .\" The default search path varies, but usually looks at a number of places below | |
203 | .\" .I /etc/locale | |
204 | .\" and | |
205 | .\" .IR /usr/lib/locale . | |
47297adb | 206 | .SH SEE ALSO |
fea681da MK |
207 | .BR catgets (3), |
208 | .BR setlocale (3) |