catopen(S)

catopen, catclose -- open/close a message catalog

Syntax

cc . . . -lc

#include  <nl_types.h>

nl_catd catopen (name, oflag)
char *name;
int oflag;

int catclose (catd)
nl_catd catd;

Description

catopen(S) opens a message catalog generated by the gencat(CP) utility and returns a catalog descriptor for use by catgets(S). The name argument is the name of the message catalog to be opened.

catclose( ) closes the message catalog identified by the catd catalog descriptor.

If name contains a ``/'' then name specifies a pathname for the message catalog. Otherwise, name must be of the form

filename[@archivename]

The pathname for the message catalog in this case is constructed from the environment variable $NLSPATH (see environ(M)) by substituting the %N component of $NLSPATH by filename and the optional %A component by archivename. If archivename is specified, catgets( ) accesses the message catalog in an archived directory.

If the environment variable $NLSPATH is not set, or if a message catalog can not be opened in any of the paths specified by $NLSPATH, then the default paths matching the following templates are used:

/usr/lib/nls/msg/%L/%A/%N
/usr/lib/nls/msg/%l_%t/%A/%N
/usr/lib/nls/msg/%l/%A/%N

/etc/nls/msg/%L/%A/%N
/etc/nls/msg/%l_%t/%A/%N
/etc/nls/msg/%l/%A/%N

In these templates,

%L: is the current value of the LC_MESSAGES category, or, if not set, C by default
%l: is the language component from the LC_MESSAGES category
%t: is the territory component from the LC_MESSAGES category
%A: is the optional archive component (archivename) of the message catalog name
%N: is the file component (filename) of the message catalog name

If the optional archive component, archivename, is not specified in name, %A is omitted when constructing pathnames for the message catalog from these templates.

The pathnames for the message catalog constructed from these templates or the environment variable $NLSPATH may be affected by the current setting of LC_MESSAGES if oflag has the value NL_CAT_LOCALE, or by the current setting of the LANG if oflag is 0.

oflag must have one of the following values. Setting oflag to any other values causes undefined behavior.

0: The current value of LANG is used to locate the catalog and the value of LC_MESSAGES is ignored.
NL_CAT_LOCALE: The current value of LC_MESSAGES is used to locate the message catalog.
NL_USE_NLSPATH: The environment variable $NLSPATH is used to locate the message catalog even if name contains a ``/''.

Return values

If successful, catopen( ) returns a message catalog descriptor for use on subsequent calls to catgets(S) and catclose( ). If unsuccessful, catopen( ) returns (nl_catd)-1.

catclose( ) returns 0 if successful; otherwise it returns -1.

Diagnostics

The catopen( ) routine fails if one of the following is true:

ENOMEM: Insufficient storage space is available.
I_EIBNV: The LANG variable is not defined or contains incorrect data.
I_ENOOP: No message file was found according to $NLSPATH.
I_ENMEM: Out of memory.

The catclose( ) routine fails if the following is true:

I_EBADC: The message file could not be found or the message catalog file descriptor has already been closed.

Notes

Using catopen( ) may cause another file descriptor to be allocated by the calling process, in addition to stdin, stdout and stderr. Applications should take care not to close this file descriptor by mistake.

Standards conformance

catopen(S) and catclose(S) are conformant with:

X/Open Portability Guide, Issue 3, 1989 .