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