1CATOPEN(3P)                POSIX Programmer's Manual               CATOPEN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       catopen — open a message catalog
14

SYNOPSIS

16       #include <nl_types.h>
17
18       nl_catd catopen(const char *name, int oflag);
19

DESCRIPTION

21       The catopen() function shall open a message catalog and return  a  mes‐
22       sage  catalog  descriptor.  The name argument specifies the name of the
23       message catalog to be opened. If name contains a '/', then name  speci‐
24       fies  a  complete name for the message catalog. Otherwise, the environ‐
25       ment variable NLSPATH is used with name substituted for the %N  conver‐
26       sion  specification  (see  the Base Definitions volume of POSIX.1‐2008,
27       Chapter 8, Environment Variables).  If NLSPATH exists in  the  environ‐
28       ment when the process starts, then if the process has appropriate priv‐
29       ileges, the behavior of catopen() is undefined.  If  NLSPATH  does  not
30       exist  in  the  environment, or if a message catalog cannot be found in
31       any of the components specified by  NLSPATH,  then  an  implementation-
32       defined default path shall be used. This default may be affected by the
33       setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE,  or  the
34       LANG environment variable if oflag is 0.
35
36       A message catalog descriptor shall remain valid in a process until that
37       process closes it, or a successful call to one of the exec functions. A
38       change in the setting of the LC_MESSAGES category may invalidate exist‐
39       ing open catalogs.
40
41       If a file descriptor is used to implement message catalog  descriptors,
42       the FD_CLOEXEC flag shall be set; see <fcntl.h>.
43
44       If  the value of the oflag argument is 0, the LANG environment variable
45       is used to locate the catalog without regard to the  LC_MESSAGES  cate‐
46       gory.  If the oflag argument is NL_CAT_LOCALE, the LC_MESSAGES category
47       is used to locate the message catalog (see the Base Definitions  volume
48       of POSIX.1‐2008, Section 8.2, Internationalization Variables).
49

RETURN VALUE

51       Upon  successful  completion,  catopen() shall return a message catalog
52       descriptor for use on subsequent calls  to  catgets()  and  catclose().
53       Otherwise,  catopen()  shall return (nl_catd) −1 and set errno to indi‐
54       cate the error.
55

ERRORS

57       The catopen() function may fail if:
58
59       EACCES Search permission is denied for the component of the path prefix
60              of the message catalog or read permission is denied for the mes‐
61              sage catalog.
62
63       EMFILE All file descriptors available  to  the  process  are  currently
64              open.
65
66       ENAMETOOLONG
67              The  length  of  a  component  of  a  pathname  is  longer  than
68              {NAME_MAX}.
69
70       ENAMETOOLONG
71              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
72              tion  of  a symbolic link produced an intermediate result with a
73              length that exceeds {PATH_MAX}.
74
75       ENFILE Too many files are currently open in the system.
76
77       ENOENT The message catalog does not exist or the name  argument  points
78              to an empty string.
79
80       ENOMEM Insufficient storage space is available.
81
82       ENOTDIR
83              A  component  of the path prefix of the message catalog names an
84              existing file that is neither a directory nor a symbolic link to
85              a  directory, or the pathname of the message catalog contains at
86              least one non-<slash> character and ends with one or more trail‐
87              ing  <slash> characters and the last pathname component names an
88              existing file that is neither a directory nor a symbolic link to
89              a directory.
90
91       The following sections are informative.
92

EXAMPLES

94       None.
95

APPLICATION USAGE

97       Some  implementations  of  catopen() use malloc() to allocate space for
98       internal buffer areas. The catopen() function  may  fail  if  there  is
99       insufficient storage space available to accommodate these buffers.
100
101       Conforming  applications  must  assume that message catalog descriptors
102       are not valid after a call to one of the exec functions.
103
104       Application developers should be aware that guidelines for the location
105       of  message catalogs have not yet been developed. Therefore they should
106       take care to avoid conflicting with catalogs used by other applications
107       and the standard utilities.
108

RATIONALE

110       None.
111

FUTURE DIRECTIONS

113       None.
114

SEE ALSO

116       catclose(), catgets()
117
118       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
119       Variables, <fcntl.h>, <nl_types.h>,
120
122       Portions of this text are reprinted and reproduced in  electronic  form
123       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
124       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
125       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
126       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
127       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
128       event of any discrepancy between this version and the original IEEE and
129       The  Open Group Standard, the original IEEE and The Open Group Standard
130       is the referee document. The original Standard can be  obtained  online
131       at http://www.unix.org/online.html .
132
133       Any  typographical  or  formatting  errors that appear in this page are
134       most likely to have been introduced during the conversion of the source
135       files  to  man page format. To report such errors, see https://www.ker
136       nel.org/doc/man-pages/reporting_bugs.html .
137
138
139
140IEEE/The Open Group                  2013                          CATOPEN(3P)
Impressum