Get rid of __const.
[dragonfly.git] / lib / libcr / 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/libcr/nls/Attic/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 .