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