HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

c
catopen(3C) catopen(3C)
NAME
catopen(), catclose() - open and close a message catalog for reading
SYNOPSIS
#include <nl_types.h>
nl_catd catopen(const char *name, int oflag);
int catclose(nl_catd catd);
DESCRIPTION
The catopen() function opens a message catalog and returns a catalog descriptor. The
name specifies
the name of the message catalog being opened. A
name containing a slash (/) specifies a path name for the
message catalog. Otherwise, the environment variable
NLSPATH is used (see environ(5)). If
NLSPATH
specifies more than one path, catopen()
returns the catalog descriptor for the first path on which it is
able to successfully open the specified message catalog. If
NLSPATH does not exist in the environment, or
if a message catalog cannot be opened for any
NLSPATH-specified path, catopen() uses a system-wide
default path. The default is affected by
LC_MESSAGES if the value of oflag is NL_CAT_LOCALE
.If
the value of
oflag is zero, the default is affected by the environment variable LANG
. See environ(5) for
details.
If
catopen() is invoked from a setuid or setgid programs with owner root and executed by others,
the environment variable NLSPATH is not directly used to locate message catalogs. Instead, the paths
which are available in both the configuration file /etc/default/nlspath
and environment variable
NLSPATH are considered to locate message catalogs. See nlspath(4) for details.
For example, if the environment variable is set to
NLSPATH=/usr/lib/nls/msg/%L/%N.cat:/tmp/%L/%N.cat
and the configuration file has an
entry
NLSPATH=/usr/lib/nls/msg/%L/%N.cat
, only the path
/usr/lib/nls/msg/%L/%N.cat
is considered for locating catalog files. This feature is provided only
for backward compatibility for those
setuid or setgid root programs which are depending on environ-
ment variable
NLSPATH. All new setgid or setuid root programs should not depend on environment
variable NLSPATH and use only absolute path names.
A message catalog descriptor remains valid in a process until the process closes it, or until a successful call
to one of the exec() functions. A change in the setting of the LC_MESSAGES category may invalidate
existing open catalogs.
If a file descriptor is used to implement message catalog descriptors, the
FD_CLOEXEC flag will be set.
If
oflag is zero, the LANG environment variable is used to locate the catalog. If oflag
is
NL_CAT_LOCALE, the LC_MESSAGES
category is used to locate the message catalog only if a successful
call to
setlocale() has been made prior to the call to catopen(). The result of setting
oflag to
any other value is undefined.
The
catclose() function closes the message catalog catd, a message catalog descriptor returned from
an earlier successful call to catopen() .
RETURN VALUE
Upon success, catopen() returns a message catalog descriptor. Otherwise, catopen() returns a
value of (nl_catd)− 1 and sets errno to indicate the error.
Upon success, catclose() returns zero. Otherwise, catclose() returns −1 and sets errno to indi-
cate the error.
ERRORS
catopen() fails without opening a message catalog, and sets errno for the last path attempted under
any of the following conditions:
[EACCES] A component of the path prefix denies search permission, or read permission
is denied for the named file.
[EMFILE] The maximum number of file descriptors allowed are currently open.
[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the
length of a component of the path name exceeds NAME_MAX bytes while
_POSIX_NO_TRUNC is in effect.
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−61