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 and 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 .B 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 \fI(nl_catd)\ \-1\fP
 119 and sets
 120 .I errno
 121 to indicate the error.
 122 The possible error values include all
 123 possible values for the
 124 .BR open (2)
 125 call.
 126 .LP
 127 The function
 128 .BR catclose ()
 129 returns 0 on success, or \-1 on failure.
 130 .SH ENVIRONMENT
 131 .TP
 132 .B LC_MESSAGES
 133 May be the source of the
 134 .B LC_MESSAGES
 135 locale setting, and thus
 136 determine the language to use if
 137 .I flag
 138 is set to
 139 .BR NL_CAT_LOCALE .
 140 .TP
 141 .B LANG
 142 The language to use if
 143 .I flag
 144 is 0.
 145 .SH CONFORMING TO
 146 POSIX.1-2001.
 147 .\" In XPG 1987, Vol. 3 it says:
 148 .\" .I "The flag argument of catopen is reserved for future use"
 149 .\" .IR "and should be set to 0" .
 150 It is unclear what the source was for the constants
 151 .B MCLoadBySet
 152 and
 153 .B MCLoadAll
 154 (see below).
 155 .SH NOTES
 156 The above is the POSIX.1-2001 description.
 157 The glibc value for
 158 .B NL_CAT_LOCALE
 159 is 1.
 160 (Compare
 161 .B MCLoadAll
 162 below.)
 163 The default path varies, but usually looks at a number of places below
 164 .IR /usr/share/locale .
 165 .SS Linux notes
 166 These functions are available for Linux since libc 4.4.4c.
 167 In the case of linux libc4 and libc5, the catalog descriptor
 168 .I nl_catd
 169 is a
 170 .BR mmap (2)'ed
 171 area of memory and not a file descriptor.
 172 The
 173 .I flag
 174 argument to
 175 .BR catopen ()
 176 should be either
 177 .B MCLoadBySet
 178 (=0) or
 179 .B MCLoadAll
 180 (=1).
 181 The former value indicates that a set from the catalog is to be
 182 loaded when needed, whereas the latter causes the initial call to
 183 .BR catopen ()
 184 to load the entire catalog into memory.
 185 The default search path varies, but usually looks at a number of places below
 186 .I /etc/locale
 187 and
 188 .IR /usr/lib/locale .
 189 .SH SEE ALSO
 190 .BR catgets (3),
 191 .BR setlocale (3)