man3/catopen.3

   1 .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-applied-psychology.cambridge.ac.uk>
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze <joey@infodrom.org>
  24 .\" Modified 2001-12-14 aeb
  25 .\"
  26 .TH CATOPEN 3 2001-12-14
  27 .SH NAME
  28 catopen, catclose \- open/close a message catalog
  29 .SH SYNOPSIS
  30 .B #include <nl_types.h>
  31 .sp
  32 .BI "nl_catd catopen(const char *" name ", int " flag );
  33 .br
  34 .BI "int catclose(nl_catd " catalog );
  35 .SH DESCRIPTION
  36 The function
  37 .B catopen()
  38 opens a message catalog and returns a catalog descriptor.
  39 The descriptor remains valid until catclose() or exec().
  40 If a file descriptor is used to implement catalog descriptors
  41 then the FD_CLOEXEC flag will be set.
  42 .LP
  43 The argument
  44 .I name
  45 specifies the name of the message catalog to be opened.
  46 If
  47 .I name
  48 specifies and absolute path (i.e., contains a '/'),
  49 then
  50 .I name
  51 specifies a pathname for the message catalog.
  52 Otherwise, the environment variable
  53 .B NLSPATH
  54 is used with
  55 .I name
  56 substituted for
  57 .B %N
  58 (see
  59 .BR locale (7)).
  60 It is unspecified whether
  61 .B NLSPATH
  62 will be used when the process has root privileges.
  63 If
  64 .B NLSPATH
  65 does not exist in the environment,
  66 or if a message catalog cannot be opened
  67 in any of the paths specified by it,
  68 then an implementation defined path is used.
  69 This latter default path may depend on the
  70 .B LC_MESSAGES
  71 locale setting when the
  72 .I flag
  73 argument is
  74 .B NL_CAT_LOCALE
  75 and on the
  76 .B LANG
  77 environment variable when the
  78 .I flag
  79 argument is 0.
  80 Changing the LC_MESSAGES part of the locale may invalidate
  81 open catalog descriptors.
  82 .LP
  83 The
  84 .I flag
  85 argument to
  86 .B catopen()
  87 is used to indicate the source for the language to use.
  88 If it is set to
  89 .B NL_CAT_LOCALE
  90 then it will use the current locale setting for
  91 .BR LC_MESSAGES .
  92 Otherwise it will use the
  93 .B LANG
  94 environment variable.
  95 .LP
  96 The function
  97 .B catclose()
  98 closes the message catalog identified by
  99 .IR catalog .
 100 It invalidates any subsequent references to the message catalog
 101 defined by
 102 .IR catalog .
 103 .LP
 104 .SH "RETURN VALUE"
 105 The function
 106 .B catopen()
 107 returns a message catalog descriptor of type
 108 .I nl_catd
 109 on success.
 110 On failure, it returns (nl_catd) \-1
 111 and sets
 112 .I errno
 113 to indicate the error. The possible error values include all
 114 possible values for the
 115 .I open()
 116 call.
 117 .LP
 118 The function
 119 .B catclose()
 120 returns 0 on success, or \-1 on failure.
 121 .SH ENVIRONMENT
 122 .TP
 123 .B LC_MESSAGES
 124 May be the source of the LC_MESSAGES locale setting, and thus
 125 determine the language to use if
 126 .I flag
 127 is set to
 128 .BR NL_CAT_LOCALE .
 129 .TP
 130 .B LANG
 131 The language to use if
 132 .I flag
 133 is 0.
 134 .SH NOTES
 135 The above is the POSIX 1003.1-2001 description.
 136 The glibc value for NL_CAT_LOCALE is 1.
 137 (Compare MCLoadAll below.)
 138 The default path varies, but usually looks at a number of places below
 139 .IR /usr/share/locale .
 140 .SH "NOTES FOR LIBC4 AND LIBC5"
 141 These functions are available for Linux since libc 4.4.4c.
 142 In the case of linux libc4 and libc5, the catalog descriptor
 143 .I nl_catd
 144 is a mmap()'ed area of memory and not a file descriptor.
 145 The
 146 .I flag
 147 argument to
 148 .B catopen()
 149 should be either
 150 .B MCLoadBySet
 151 (=0) or
 152 .B MCLoadAll
 153 (=1).
 154 The former value indicates that a set from the catalog is to be
 155 loaded when needed, whereas the latter causes the initial call to
 156 .BR catopen ()
 157 to load the entire catalog into memory.
 158 The default search path varies, but usually looks at a number of places below
 159 .I /etc/locale
 160 and
 161 .IR /usr/lib/locale .
 162 .SH "CONFORMING TO"
 163 POSIX 1003.1-2001.
 164 In XPG 1987, Vol. 3 it says:
 165 .I "The flag argument of catopen is reserved for future use"
 166 .IR "and should be set to 0" .
 167 It is unclear what the source was for the constants MCLoadBySet
 168 and MCLoadAll.
 169 .SH "SEE ALSO"
 170 .BR catgets (3),
 171 .BR setlocale (3)