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