man3/catopen.3

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