original/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 2001-12-14 "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 CONFORMING TO
 147 POSIX.1-2001.
 148 .\" In XPG 1987, Vol. 3 it says:
 149 .\" .I "The flag argument of catopen is reserved for future use"
 150 .\" .IR "and should be set to 0" .
 151 It is unclear what the source was for the constants
 152 .B MCLoadBySet
 153 and
 154 .B MCLoadAll
 155 (see below).
 156 .SH NOTES
 157 The above is the POSIX.1-2001 description.
 158 The glibc value for
 159 .B NL_CAT_LOCALE
 160 is 1.
 161 (Compare
 162 .B MCLoadAll
 163 below.)
 164 The default path varies, but usually looks at a number of places below
 165 .IR /usr/share/locale .
 166 .SS Linux notes
 167 These functions are available for Linux since libc 4.4.4c.
 168 In the case of linux libc4 and libc5, the catalog descriptor
 169 .I nl_catd
 170 is a
 171 .BR mmap (2)'ed
 172 area of memory and not a file descriptor.
 173 The
 174 .I flag
 175 argument to
 176 .BR catopen ()
 177 should be either
 178 .B MCLoadBySet
 179 (=0) or
 180 .B MCLoadAll
 181 (=1).
 182 The former value indicates that a set from the catalog is to be
 183 loaded when needed, whereas the latter causes the initial call to
 184 .BR catopen ()
 185 to load the entire catalog into memory.
 186 The default search path varies, but usually looks at a number of places below
 187 .I /etc/locale
 188 and
 189 .IR /usr/lib/locale .
 190 .SH SEE ALSO
 191 .BR catgets (3),
 192 .BR setlocale (3)
 193 .SH COLOPHON
 194 This page is part of release 3.68 of the Linux
 195 .I man-pages
 196 project.
 197 A description of the project,
 198 information about reporting bugs,
 199 and the latest version of this page,
 200 can be found at
 201 \%http://www.kernel.org/doc/man\-pages/.