gettext: Interface to catgets
1
1 11.1.1 The Interface
1 --------------------
1
1 The interface to the ‘catgets’ implementation consists of three
1 functions which correspond to those used in file access: ‘catopen’ to
1 open the catalog for using, ‘catgets’ for accessing the message tables,
1 and ‘catclose’ for closing after work is done. Prototypes for the
1 functions and the needed definitions are in the ‘<nl_types.h>’ header
1 file.
1
1 ‘catopen’ is used like in this:
1
1 nl_catd catd = catopen ("catalog_name", 0);
1
1 The function takes as the argument the name of the catalog. This
1 usual refers to the name of the program or the package. The second
1 parameter is not further specified in the standard. I don’t even know
1 whether it is implemented consistently among various systems. So the
1 common advice is to use ‘0’ as the value. The return value is a handle
1 to the message catalog, equivalent to handles to file returned by
1 ‘open’.
1
1 This handle is of course used in the ‘catgets’ function which can be
1 used like this:
1
1 char *translation = catgets (catd, set_no, msg_id, "original string");
1
1 The first parameter is this catalog descriptor. The second parameter
1 specifies the set of messages in this catalog, in which the message
1 described by ‘msg_id’ is obtained. ‘catgets’ therefore uses a
1 three-stage addressing:
1
1 catalog name ⇒ set number ⇒ message ID ⇒ translation
1
1 The fourth argument is not used to address the translation. It is
1 given as a default value in case when one of the addressing stages fail.
1 One important thing to remember is that although the return type of
1 catgets is ‘char *’ the resulting string _must not_ be changed. It
1 should better be ‘const char *’, but the standard is published in 1988,
1 one year before ANSI C.
1
1 The last of these functions is used and behaves as expected:
1
1 catclose (catd);
1
1 After this no ‘catgets’ call using the descriptor is legal anymore.
1