Debian Codegraph @

upstream/debian-unstable/man3/catopen.3

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