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

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

101

102

103

104

105

106

107

108

109

110

__________________________________________________________________________________________________________________________________________________________________________________________________

STANDARD Printed by: Nora Chuang [nchuang] STANDARD

/build/1111/BRICK/man3/!!!intro.3c

________________________________________________________________

___ ___

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 speciﬁes

the name of the message catalog being opened. A name containing a slash (/) speciﬁes a path name for the

message catalog. Otherwise, the environment variable NLSPATH is used (see environ(5)). If NLSPATH

speciﬁes more than one path, catopen() returns the catalog descriptor for the ﬁrst path on which it is

able to successfully open the speciﬁed message catalog. If NLSPATH does not exist in the environment, or

if a message catalog cannot be opened for any NLSPATH-speciﬁed 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.

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 ﬁle descriptor is used to implement message catalog descriptors, the

FD_CLOEXEC ﬂag will be set.

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

any other value is undeﬁned.

The

catclose() function closes the message catalog catd, a message catalog descriptor returned from

an earlier successful call to catopen().

APPLICATION USAGE

catopen() and catclose() are thread-safe. These interfaces are not async-cancel-safe. A cancellation

point may occur when a thread is executing catopen() or catclose().

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 preﬁx denies search permission, or read permission

is denied for the named ﬁle.

[EMFILE] The maximum number of ﬁle descriptors allowed are currently open.

[ENAMETOOLONG] The length of the speciﬁed 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.

[ENFILE] The system ﬁle table is full.

[ENOENT] The named catalog does not exist or the path is null.

[ENOTDIR] A component of the path preﬁx is not a directory.

catgets() can be used to provide default messages when called following a failed catopen() (see

catgets(3C)). catgets() returns its def_str parameter if it is passed an invalid catalog descriptor.

catclose() fails if the following is true:

Section 3−−60 − 1 − HP-UX Release 11i: December 2000

___