Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > C

catopen(3C)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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 setuid or setgid programs with owner root, the environment variable NLSPATH is not directly used to locate message catalogs. Instead, the paths which are available both in the configuration file /etc/default/nlspath and environment variable NLSPATH are considered to locate message catalogs. See nlspath(4) for details.

Example: If the environment variable is set to:

NLSPATH=/usr/lib/nls/msg/%L/%N.cat:/tmp/%L/%N.cat

and the /etc/default/nlspath configuration file has an entry:

NLSPATH=/usr/lib/nls/msg/%L/%N.cat

only 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 the NLSPATH environment variable. All new setgid or setuid root programs should not depend on the NLSPATH environment variable and should only use 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.

A file descriptor is used to implement the message catalog descriptor and the close-on-exec flag is set for the message catalog descriptor (see fcntl(2)).

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 indicate 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.

ENFILE

The system file table is full.

ENOENT

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

ENOTDIR

A component of the path prefix 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:

EBADF

catd is not a valid open message catalog descriptor.

WARNINGS

When using NLSPATH, catopen() does not provide a default value for LANG.

AUTHOR

catopen() and catclose() were developed by HP.

FILES

/usr/include/nl_types.h

Include file containing native language types.

/usr/lib/nls/msg

Message catalog default path for core HP-UX products only.

STANDARDS CONFORMANCE

catopen(): AES, SVID3, XPG2, XPG3, XPG4

catclose(): AES, SVID3, XPG2, XPG3, XPG4

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.