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