man3/catopen.3

   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)