lib/libc/nls/catopen.3

   1 .\" Copyright (c) 1994 Winning Strategies, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"      This product includes software developed by Winning Strategies, Inc.
  15 .\" 4. The name of the author may not be used to endorse or promote products
  16 .\"    derived from this software without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .Dd February 12, 2005
  29 .Dt CATOPEN 3
  30 .Os
  31 .Sh NAME
  32 .Nm catopen
  33 .Nd open message catalog
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In nl_types.h
  38 .Ft nl_catd
  39 .Fn catopen "const char *name" "int oflag"
  40 .Sh DESCRIPTION
  41 The
  42 .Fn catopen
  43 function opens the message catalog specified by
  44 .Fa name
  45 and returns a message catalog descriptor.
  46 If
  47 .Fa name
  48 contains a
  49 .Sq /
  50 then
  51 .Fa name
  52 specifies the full pathname for the message catalog, otherwise the value
  53 of the environment variable
  54 .Ev NLSPATH
  55 is used with
  56 the following substitutions:
  57 .Bl -tag -width XXX
  58 .It \&%N
  59 The value of the
  60 .Fa name
  61 argument.
  62 .It \&%L
  63 The value of the
  64 .Ev LANG
  65 environment variable or the
  66 .Dv LC_MESSAGES
  67 category (see below).
  68 .It \&%l
  69 The language element from the
  70 .Ev LANG
  71 environment variable or from the
  72 .Dv LC_MESSAGES
  73 category.
  74 .It \&%t
  75 The territory element from the
  76 .Ev LANG
  77 environment variable or from the
  78 .Dv LC_MESSAGES
  79 category.
  80 .It \&%c
  81 The codeset element from the
  82 .Ev LANG
  83 environment variable or from the
  84 .Dv LC_MESSAGES
  85 category.
  86 .It \&%%
  87 A single % character.
  88 .El
  89 .Pp
  90 An empty string is substituted for undefined values.
  91 .Pp
  92 Path names templates defined in
  93 .Ev NLSPATH
  94 are separated by colons
  95 .Pq Sq \&: .
  96 A leading or two adjacent colons
  97 is equivalent to specifying %N.
  98 .Pp
  99 If the
 100 .Fa oflag
 101 argument is set to the
 102 .Dv NL_CAT_LOCALE
 103 constant,
 104 .Dv LC_MESSAGES
 105 locale category used to open the message catalog; using
 106 .Dv NL_CAT_LOCALE
 107 conforms to the
 108 .St -xpg4
 109 standard.
 110 You can specify 0 for compatibility with
 111 .St -xpg3 ;
 112 when
 113 .Fa oflag
 114 is set to 0, the
 115 .Ev LANG
 116 environment variable
 117 determines the message catalog locale.
 118 .Pp
 119 A message catalog descriptor
 120 remains valid in a process until that process closes it, or
 121 until a successful call to one of the
 122 .Xr exec 3
 123 function.
 124 .Sh RETURN VALUES
 125 Upon successful completion,
 126 .Fn catopen
 127 returns a message catalog descriptor.
 128 Otherwise, (nl_catd) -1 is returned and
 129 .Va errno
 130 is set to indicate the error.
 131 .Sh ERRORS
 132 .Bl -tag -width Er
 133 .It Bq Er EINVAL
 134 Argument
 135 .Fa name
 136 does not point to a valid message catalog, or catalog is corrupt.
 137 .It Bq Er ENAMETOOLONG
 138 An entire path to the message catalog exceeded 1024 characters.
 139 .It Bq Er ENOENT
 140 The named message catalog does not exists, or the
 141 .Fa name
 142 argument points to an empty string.
 143 .It Bq Er ENOMEM
 144 Insufficient memory is available.
 145 .El
 146 .Sh SEE ALSO
 147 .Xr gencat 1 ,
 148 .Xr catclose 3 ,
 149 .Xr catgets 3 ,
 150 .Xr setlocale 3
 151 .Sh STANDARDS
 152 The
 153 .Fn catopen
 154 function conforms to
 155 .St -p1003.1-2001 .