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 .\"
  29 .\" $FreeBSD: src/lib/libc/nls/catopen.3,v 1.9.2.6 2001/12/14 18:33:56 ru Exp $
  30 .\" $DragonFly: src/lib/libc/nls/catopen.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
  31 .Dd May 29, 1994
  32 .Dt CATOPEN 3
  33 .Os
  34 .Sh NAME
  35 .Nm catopen
  36 .Nd open message catalog
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In nl_types.h
  41 .Ft nl_catd
  42 .Fn catopen "const char *name" "int oflag"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn catopen
  46 function opens the message catalog specified by
  47 .Fa name
  48 and returns a message catalog descriptor.
  49 If
  50 .Fa name
  51 contains a
  52 .Sq /
  53 then
  54 .Fa name
  55 specifies the full pathname for the message catalog, otherwise the value
  56 of the environment variable
  57 .Ev NLSPATH
  58 is used with
  59 the following substitutions:
  60 .Bl -tag -width XXX
  61 .It \&%N
  62 The value of the
  63 .Fa name
  64 argument.
  65 .It \&%L
  66 The value of the
  67 .Ev LANG
  68 environment variable or the
  69 .Dv LC_MESSAGES
  70 category (see below).
  71 .It \&%l
  72 The language element from the
  73 .Ev LANG
  74 environment variable or from the
  75 .Dv LC_MESSAGES
  76 category.
  77 .It \&%t
  78 The territory element from the
  79 .Ev LANG
  80 environment variable or from the
  81 .Dv LC_MESSAGES
  82 category.
  83 .It \&%c
  84 The codeset element from the
  85 .Ev LANG
  86 environment variable or from the
  87 .Dv LC_MESSAGES
  88 category.
  89 .It \&%%
  90 A single % character.
  91 .El
  92 .Pp
  93 An empty string is substituted for undefined values.
  94 .Pp
  95 Path names templates defined in
  96 .Ev NLSPATH
  97 are separated by colons
  98 .No ( Sq \&: ) .
  99 A leading or two adjacent colons
 100 is equivalent to specifying %N.
 101 .Pp
 102 If the
 103 .Fa oflag
 104 argument is set to the
 105 .Dv NL_CAT_LOCALE
 106 constant,
 107 .Dv LC_MESSAGES
 108 locale category used to open the message catalog; using
 109 .Dv NL_CAT_LOCALE
 110 conforms to the
 111 .St -xpg4
 112 standard.
 113 You can specify 0 for compatibility with
 114 .St -xpg3 ;
 115 when
 116 .Fa oflag
 117 is set to 0, the
 118 .Ev LANG
 119 environment variable
 120 determines the message catalog locale.
 121 .Pp
 122 A message catalog descriptor
 123 remains valid in a process until that process closes it, or
 124 until a successful call to one of the
 125 .Xr exec 3
 126 function.
 127 .Sh RETURN VALUES
 128 Upon successful completion,
 129 .Fn catopen
 130 returns a message catalog descriptor.
 131 Otherwise, (nl_catd) -1 is returned and
 132 .Va errno
 133 is set to indicate the error.
 134 .Sh ERRORS
 135 .Bl -tag -width Er
 136 .It Bq Er EINVAL
 137 Argument
 138 .Fa name
 139 does not point to a valid message catalog.
 140 .It Bq Er ENAMETOOLONG
 141 An entire path to the message catalog exceeded 1024 characters.
 142 .It Bq Er ENOENT
 143 The named message catalog does not exists, or the
 144 .Fa name
 145 argument points to an empty string.
 146 .It Bq Er ENOMEM
 147 Insufficient memory is available.
 148 .El
 149 .Sh SEE ALSO
 150 .Xr gencat 1 ,
 151 .Xr catclose 3 ,
 152 .Xr catgets 3 ,
 153 .Xr setlocale 3
 154 .Sh STANDARDS
 155 The
 156 .Fn catopen
 157 function conforms to
 158 .St -xpg4 .