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