Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

catopen(3) OSS Library Calls Reference Manual
For example, if the catopen( ) function specifies a catalog with the name mycmd.cat, and the
environment variables are set as follows:
NLSPATH=../%N:/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%l/%N
LANG=fr_BE.ISO8859-1
then 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 application program must call setlocale( ) to set the
LC_MESSAGES category before calling catopen( ).
NOTES
The catopen( ) call may defer the opening of the file until the first call to catgets( ) for that mes-
sage catalog. This eliminates or defers the overhead involved in opening a file. If a program
opens a message catalog but does not need to get a message from it, this can improve the pro-
gram execution. If the program does need to get a message, this deferral can improve the speed
of program start up.
If the call to catopen( ) defers the opening of the message file, catopen( ) always returns a valid
catalog descriptor and will not set errno. In this case, you cannot directly determine if the cata-
log open succeeds. You can indirectly check if the catalog open succeeds by comparing the
address of the string that the catgets( ) function returns with the address of the default string. If
the function returns the default 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).
RELATED INFORMATION
Functions: catgets(3), catclose(3), setlocale(3).
Commands: gencat(1).
1−90 Hewlett-Packard Company 527187-017