]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk> |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze <joey@infodrom.org> | |
7 | .\" Modified 2001-12-14 aeb | |
8 | .\" | |
4c1c5274 | 9 | .TH catopen 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
10 | .SH NAME |
11 | catopen, catclose \- open/close a message catalog | |
b813014f AC |
12 | .SH LIBRARY |
13 | Standard C library | |
14 | .RI ( libc ", " \-lc ) | |
fea681da | 15 | .SH SYNOPSIS |
7b5d39f4 | 16 | .nf |
fea681da | 17 | .B #include <nl_types.h> |
68e4db0a | 18 | .PP |
fea681da | 19 | .BI "nl_catd catopen(const char *" name ", int " flag ); |
fea681da | 20 | .BI "int catclose(nl_catd " catalog ); |
7b5d39f4 | 21 | .fi |
fea681da MK |
22 | .SH DESCRIPTION |
23 | The function | |
63aa9df0 | 24 | .BR catopen () |
fea681da | 25 | opens a message catalog and returns a catalog descriptor. |
c13182ef MK |
26 | The descriptor remains valid until |
27 | .BR catclose () | |
28 | or | |
fb186734 | 29 | .BR execve (2). |
b0b89919 | 30 | If a file descriptor is used to implement catalog descriptors, |
1274071a MK |
31 | then the |
32 | .B FD_CLOEXEC | |
33 | flag will be set. | |
dd3568a1 | 34 | .PP |
fea681da MK |
35 | The argument |
36 | .I name | |
37 | specifies the name of the message catalog to be opened. | |
38 | If | |
39 | .I name | |
b957f81f | 40 | specifies an absolute path (i.e., contains a \[aq]/\[aq]), |
fea681da MK |
41 | then |
42 | .I name | |
43 | specifies a pathname for the message catalog. | |
44 | Otherwise, the environment variable | |
45 | .B NLSPATH | |
46 | is used with | |
47 | .I name | |
48 | substituted for | |
49 | .B %N | |
50 | (see | |
51 | .BR locale (7)). | |
52 | It is unspecified whether | |
53 | .B NLSPATH | |
54 | will be used when the process has root privileges. | |
55 | If | |
56 | .B NLSPATH | |
57 | does not exist in the environment, | |
58 | or if a message catalog cannot be opened | |
59 | in any of the paths specified by it, | |
60 | then an implementation defined path is used. | |
61 | This latter default path may depend on the | |
62 | .B LC_MESSAGES | |
63 | locale setting when the | |
64 | .I flag | |
65 | argument is | |
66 | .B NL_CAT_LOCALE | |
67 | and on the | |
68 | .B LANG | |
69 | environment variable when the | |
70 | .I flag | |
71 | argument is 0. | |
2f0af33b MK |
72 | Changing the |
73 | .B LC_MESSAGES | |
74 | part of the locale may invalidate | |
fea681da | 75 | open catalog descriptors. |
dd3568a1 | 76 | .PP |
fea681da MK |
77 | The |
78 | .I flag | |
79 | argument to | |
63aa9df0 | 80 | .BR catopen () |
fea681da MK |
81 | is used to indicate the source for the language to use. |
82 | If it is set to | |
b0b89919 | 83 | .BR NL_CAT_LOCALE , |
fea681da MK |
84 | then it will use the current locale setting for |
85 | .BR LC_MESSAGES . | |
2b9b829d | 86 | Otherwise, it will use the |
fea681da MK |
87 | .B LANG |
88 | environment variable. | |
dd3568a1 | 89 | .PP |
fea681da | 90 | The function |
63aa9df0 | 91 | .BR catclose () |
fea681da MK |
92 | closes the message catalog identified by |
93 | .IR catalog . | |
94 | It invalidates any subsequent references to the message catalog | |
95 | defined by | |
96 | .IR catalog . | |
47297adb | 97 | .SH RETURN VALUE |
fea681da | 98 | The function |
63aa9df0 | 99 | .BR catopen () |
fea681da MK |
100 | returns a message catalog descriptor of type |
101 | .I nl_catd | |
102 | on success. | |
c9942389 | 103 | On failure, it returns |
1ae6b2c7 | 104 | .I (nl_catd)\~\-1 |
fea681da | 105 | and sets |
1bf89c60 | 106 | .I errno |
c13182ef MK |
107 | to indicate the error. |
108 | The possible error values include all | |
fea681da | 109 | possible values for the |
fb186734 | 110 | .BR open (2) |
fea681da | 111 | call. |
dd3568a1 | 112 | .PP |
fea681da | 113 | The function |
63aa9df0 | 114 | .BR catclose () |
fea681da MK |
115 | returns 0 on success, or \-1 on failure. |
116 | .SH ENVIRONMENT | |
117 | .TP | |
118 | .B LC_MESSAGES | |
2f0af33b MK |
119 | May be the source of the |
120 | .B LC_MESSAGES | |
121 | locale setting, and thus | |
fea681da MK |
122 | determine the language to use if |
123 | .I flag | |
124 | is set to | |
125 | .BR NL_CAT_LOCALE . | |
126 | .TP | |
127 | .B LANG | |
128 | The language to use if | |
129 | .I flag | |
130 | is 0. | |
0af646b2 PH |
131 | .SH ATTRIBUTES |
132 | For an explanation of the terms used in this section, see | |
133 | .BR attributes (7). | |
134 | .TS | |
135 | allbox; | |
c466875e | 136 | lbx lb lb |
0af646b2 PH |
137 | l l l. |
138 | Interface Attribute Value | |
139 | T{ | |
9e54434e BR |
140 | .na |
141 | .nh | |
0af646b2 PH |
142 | .BR catopen () |
143 | T} Thread safety MT-Safe env | |
144 | T{ | |
9e54434e BR |
145 | .na |
146 | .nh | |
0af646b2 PH |
147 | .BR catclose () |
148 | T} Thread safety MT-Safe | |
149 | .TE | |
c466875e | 150 | .sp 1 |
4131356c | 151 | .SH VERSIONS |
493d9724 | 152 | The above is the POSIX.1 description. |
2f0af33b MK |
153 | The glibc value for |
154 | .B NL_CAT_LOCALE | |
155 | is 1. | |
3ef5eb12 MK |
156 | .\" (Compare |
157 | .\" .B MCLoadAll | |
158 | .\" below.) | |
fea681da MK |
159 | The default path varies, but usually looks at a number of places below |
160 | .IR /usr/share/locale . | |
3ef5eb12 MK |
161 | .\" .SS Linux notes |
162 | .\" These functions are available for Linux since libc 4.4.4c. | |
163 | .\" In the case of linux libc4 and libc5, the catalog descriptor | |
164 | .\" .I nl_catd | |
165 | .\" is a | |
166 | .\" .BR mmap (2)'ed | |
167 | .\" area of memory and not a file descriptor. | |
168 | .\" The | |
169 | .\" .I flag | |
170 | .\" argument to | |
171 | .\" .BR catopen () | |
172 | .\" should be either | |
173 | .\" .B MCLoadBySet | |
174 | .\" (=0) or | |
175 | .\" .B MCLoadAll | |
176 | .\" (=1). | |
177 | .\" The former value indicates that a set from the catalog is to be | |
178 | .\" loaded when needed, whereas the latter causes the initial call to | |
179 | .\" .BR catopen () | |
180 | .\" to load the entire catalog into memory. | |
181 | .\" The default search path varies, but usually looks at a number of places below | |
182 | .\" .I /etc/locale | |
183 | .\" and | |
184 | .\" .IR /usr/lib/locale . | |
4131356c AC |
185 | .SH STANDARDS |
186 | POSIX.1-2008. | |
187 | .SH HISTORY | |
188 | POSIX.1-2001. | |
189 | .\" In XPG 1987, Vol. 3 it says: | |
190 | .\" .I "The flag argument of catopen is reserved for future use" | |
191 | .\" .IR "and should be set to 0" . | |
192 | .\" | |
193 | .\" It is unclear what the source was for the constants | |
194 | .\" .B MCLoadBySet | |
195 | .\" and | |
196 | .\" .B MCLoadAll | |
197 | .\" (see below). | |
47297adb | 198 | .SH SEE ALSO |
fea681da MK |
199 | .BR catgets (3), |
200 | .BR setlocale (3) |