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