1catopen(3C)              Standard C Library Functions              catopen(3C)
2
3
4

NAME

6       catopen, catclose - open/close a message catalog
7

SYNOPSIS

9       #include <nl_types.h>
10
11       nl_catd catopen(const char *name, int oflag);
12
13
14       int catclose(nl_catd catd);
15
16

DESCRIPTION

18       The  catopen()  function  opens a message catalog and returns a message
19       catalog descriptor. name specifies the name of the message  catalog  to
20       be  opened.  If  name  contains  a "/", then  name specifies a complete
21       pathname for the message catalog; otherwise, the  environment  variable
22       NLSPATH  is used and  /usr/lib/locale/locale/LC_MESSAGES must exist. If
23       NLSPATH does not exist in the environment, or if a message catalog can‐
24       not  be  opened  in  any  of  the  paths specified by NLSPATH, then the
25       default path /usr/lib/locale/locale/LC_MESSAGES is  used.  In  the  "C"
26       locale,   catopen()  will  always  succeed without checking the default
27       search path.
28
29
30       The names of message catalogs and their location in the filesystem  can
31       vary  from one system to another. Individual applications can choose to
32       name or locate message catalogs according to their own special needs. A
33       mechanism is therefore required to specify where the catalog resides.
34
35
36       The NLSPATH variable provides both the location of message catalogs, in
37       the form of a search path, and the naming conventions  associated  with
38       message catalog files.  For example:
39
40         NLSPATH=/nlslib/%L/%N.cat:/nlslib/%N/%L
41
42
43
44       The  metacharacter  % introduces a substitution field, where %L substi‐
45       tutes the current setting of either the LANG environment  variable,  if
46       the  value of oflag is  0, or the LC_MESSAGES category, if the value of
47       oflag is  NL_CAT_LOCALE, and  %N substitutes  the  value  of  the  name
48       parameter  passed  to  catopen(). Thus, in the above example, catopen()
49       will  search  in   /nlslib/$LANG/name.cat,  if  oflag  is  0,   or   in
50       /nlslib/{LC_MESSAGES}/name.cat, if oflag is NL_CAT_LOCALE.
51
52
53       The NLSPATH variable will normally be set up on a system wide basis (in
54       /etc/profile) and thus makes the location and naming conventions  asso‐
55       ciated with message catalogs transparent to both programs and users.
56
57
58       The full set of metacharacters is:
59
60       %N    The value of the name parameter passed to catopen().
61
62
63       %L    The value of LANG or LC_MESSAGES.
64
65
66       %l    The value of the language element of LANG or LC_MESSAGES.
67
68
69       %t    The value of the territory element of LANG or LC_MESSAGES.
70
71
72       %c    The value of the codeset element of LANG or LC_MESSAGES.
73
74
75       %%    A single %.
76
77
78
79       The  LANG  environment  variable  provides  the  ability to specify the
80       user's requirements for native languages, local customs  and  character
81       set, as an ASCII string in the form
82
83         LANG=language[_territory[.codeset]]
84
85
86
87       A  user who speaks German as it is spoken in Austria and has a terminal
88       which operates in ISO 8859/1 codeset, would want  the  setting  of  the
89       LANG variable to be
90
91         LANG=De_A.88591
92
93
94
95       With this setting it should be possible for that user to find any  rel‐
96       evant catalogs should they exist.
97
98
99       Should the LANG variable not  be  set,  the  value  of  LC_MESSAGES  as
100       returned  by setlocale() is used.  If this is NULL, the default path as
101       defined in <nl_types.h> is used.
102
103
104       A message catalogue descriptor remains valid in a  process  until  that
105       process closes it, or a successful call to one of the exec functions. A
106       change in the setting of the LC_MESSAGES category may invalidate exist‐
107       ing open catalogues.
108
109
110       If  a  file  descriptor is used to implement message catalogue descrip‐
111       tors, the FD_CLOEXEC flag will be set; see <fcntl.h>.
112
113
114       If the value of oflag argument is 0, the  LANG environment variable  is
115       used  to  locate the catalogue without regard to the  LC_MESSAGES cate‐
116       gory.  If the oflag argument is NL_CAT_LOCALE, the LC_MESSAGES category
117       is used to locate the message catalogue.
118
119
120       The  catclose() function closes the message catalog identified by catd.
121       If a file descriptor is used to implement the type nl_catd,  that  file
122       descriptor will be closed.
123

RETURN VALUES

125       Upon   successful  completion,  catopen()  returns  a  message  catalog
126       descriptor for use on  subsequent calls to  catgets()  and  catclose().
127       Otherwise it returns (nl_catd) −1.
128
129
130       Upon  successful completion, catclose() returns 0. Otherwise it returns
131       −1 and sets errno to indicate the error.
132

ERRORS

134       The catopen() function may fail if:
135
136       EACCES          Search permission is denied for the  component  of  the
137                       path prefix of the message catalogue or read permission
138                       is denied for the message catalogue.
139
140
141       EMFILE          There are OPEN_MAX file descriptors currently  open  in
142                       the calling process.
143
144
145       ENAMETOOLONG    The  length  of  the  pathname of the message catalogue
146                       exceeds PATH_MAX, or a  pathname  component  is  longer
147                       than NAME_MAX.
148
149
150       ENAMETOOLONG    Pathname  resolution  of  a  symbolic  link produced an
151                       intermediate result whose length exceeds PATH_MAX.
152
153
154       ENFILE          Too many files are currently open in the system.
155
156
157       ENOENT          The message catalogue does not exist or the name  argu‐
158                       ment points to an empty string.
159
160
161       ENOMEM          Insufficient storage space is available.
162
163
164       ENOTDIR         A component of the path prefix of the message catalogue
165                       is not a directory.
166
167
168
169       The catclose() function may fail if:
170
171       EBADF    The catalogue descriptor is not valid.
172
173
174       EINTR    The catclose() function was interrupted by a signal.
175
176

USAGE

178       The catopen() and catclose() functions can be  used  safely  in  multi‐
179       threaded  applications, as long as setlocale(3C) is not being called to
180       change the locale.
181

ATTRIBUTES

183       See attributes(5) for descriptions of the following attributes:
184
185
186
187
188       ┌─────────────────────────────┬─────────────────────────────┐
189       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
190       ├─────────────────────────────┼─────────────────────────────┤
191       │Interface Stability          │Standard                     │
192       ├─────────────────────────────┼─────────────────────────────┤
193       │MT-Level                     │MT-Safe                      │
194       └─────────────────────────────┴─────────────────────────────┘
195

SEE ALSO

197       gencat(1), catgets(3C), gettext(3C), nl_types.h(3HEAD),  setlocale(3C),
198       attributes(5), environ(5)
199
200
201
202SunOS 5.11                        29 Dec 1996                      catopen(3C)
Impressum