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