*** UNIX MANUAL PAGE BROWSER ***

catopen(3) Library Functions Manual catopen(3) NAME catopen, NLSPATH - Opening a message catalog LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <nl_types.h> nl_catd catopen( const char *name, int oflag); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: catopen(): XPG4 Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Specifies the message catalog to open. Specify the constant NL_CAT_LO- CALE to open the message catalog for the locale set for the LC_MESSAGES variable; using NL_CAT_LOCALE conforms to the XPG4 standard. You can specify 0 (zero) for compatibility with XPG3; when oflag is set to zero, the locale set for the LANG variable determines the message cata- log locale. DESCRIPTION The catopen() function opens a specified message catalog and returns a catalog descriptor that is used by the catgets() function to retrieve messages from the catalog. The name parameter specifies the name of the message catalog to be opened. If name contains a / (slash), then name specifies a full path- name for the message catalog. Otherwise, the environment variable NLSPATH is used with substitutions based on the value of the name para- meter and the value of the LC_MESSAGES setting. (See the i18n_intro(5) reference page for a description of LC_MESSAGES. See the NOTES section for a restriction that applies to use of the NLSPATH variable.) NLSPATH is a colon-separated list of pathnames. The catopen() function makes variable substitutions in each pathname and attempts to open the specified catalog. If the open operation succeeds, the function returns the catalog descriptor for that catalog. If the open operation does not succeed, the function attempts to open the next pathname in the value of the NLSPATH environment variable. If NLSPATH does not exist in the environment, then the function uses the following system default for NLSPATH: /usr/lib/nls/msg/%L/%N Note that current industry standards do not specify the location of message catalogs, so application developers should consider this de- fault to be platform specific. If no message catalog can be opened in any of the components specified by NLSPATH, then catopen() returns a value of -1 cast to (nl_catd). This is not a valid catalog descriptor and causes subsequent calls to catgets() to return a pointer to the default message string. The meaning of each variable in the NLSPATH environment variable is as follows: The value passed in the name parameter. The current locale name defined for the LC_MESSAGES category, for example, fr_BE.ISO8859-1. The language element of the current locale name, for example, fr. The territory element from the current locale name, for example, BE. The code set element from the current locale name, for example, ISO8859-1. A single % (percent sign) character. For example, assume that the catopen() function specifies a catalog with the name mycmd.cat, and the environment variables are set as fol- lows: NLSPATH=../%N:/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%l/%N LANG=fr_BE.ISO8859-1 Under these settings, the application searches for the catalog in the following order: ../mycmd.cat /usr/lib/nls/msg/fr_BE.ISO88591-1/mycmd.cat /usr/lib/nls/msg/fr/mycmd.cat The setlocale() function sets the value of the LC_MESSAGES category based on the values of the parameters to setlocale() and on the values of the LC_MESSAGES, LANG, and LC_ALL environment variables. The appli- cation program must call setlocale() to set the LC_MESSAGES category before calling catopen(). The descriptor for a message catalog remains valid in a process until one of the following occurs: The process closes the catalog descriptor. For example, the application executes a successful call to the cat- close() function. The application executes a successful call to one of the exec() functions. In addition, a change in the setting of LC_MESSAGES may invalidate de- scriptors for catalogs that are currently open. NOTES [Digital] When running in a process whose effective user ID (set through the setuid() call) is root, the catopen() function ignores the NLSPATH setting and searches for message catalogs by using the default path /usr/lib/nls/msg/%L/%N. Therefore, if a program uses the setuid() call to change its effective user ID to root, either the program's mes- sage catalogs or links to its message catalogs must reside in default directories. This restriction exists to ensure system security. The restriction does not apply to a program whose real user ID is root. (In other words, the restriction does not apply to a program that is run by a user logged in to the root account.) [Digital] On DIGITAL UNIX systems, a message catalog is not opened un- til the first catgets call that refers to the catalog. Therefore, the overhead associated with opening the catalog: Does not affect the speed of program startup Is eliminated altogether if the catalog is not used during a particular program execution cycle [Digital] Because the operation of opening the message catalog is de- ferred, the catopen() function always returns a valid catalog descrip- tor and sets errno for a very limited number of conditions. Therefore, applications cannot directly determine if the catalog open succeeds. They can indirectly check if the catalog open succeeds by comparing the address of the string that the catgets() function returns with the ad- dress of the default string. If the catgets() function returns the de- fault string, then either the catalog open failed or the catalog does not contain the requested message. RETURN VALUES When successful, the catopen() function returns a catalog descriptor that can be used in calls to the catgets() and catclose() functions. When the catopen() function does not succeed, it returns a value of -1 cast to (nl_catd). ERRORS If any of the following conditions occur, the catopen() function sets errno to the corresponding value. [Digital] See the NOTES section for information on the impact of de- ferred open. A signal was caught during the function. The length of the path of the file exceeds PATH_MAX, or a pathname component is longer than NAME_MAX. Insufficient memory is available. RELATED INFORMATION Functions: catgets(3), catclose(3), setlocale(3) Commands: dspcat(1), dspmsg(1), extract(1), gencat(1), mkcatdefs(1), strextract(1), strmerge(1), trans(1) Others: i18n_intro(5), l10n_intro(5), standards(5) Writing Software for the International Market delim off catopen(3)