NAME    [Toc]    [Back]

       catgets - Retrieve a message from a catalog

SYNOPSIS    [Toc]    [Back]

       #include <nl_types.h>

       char *catgets(
               nl_catd cat_descriptor,
               int set_number,
               int message_number,
               const char *string );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       catgets(): XSH5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Specifies  a  catalog  descriptor  that is returned by the
       catopen() function.  Identifies a message set.  Identifies
       a message. In combination, the set_number and message_number
 identify the particular  message  in  the  catalog  to
       retrieve.   Specifies  the  default  message  string to be
       returned if catgets() cannot retrieve the message from the
       catalog.

DESCRIPTION    [Toc]    [Back]

       The  catgets() function retrieves a message from a catalog
       after a successful call to the catopen() function. If  the
       catgets()  function finds the specified message, a pointer
       to the message text is returned. Otherwise,  the  function
       returns a pointer to the default message string.

NOTES    [Toc]    [Back]

       The  returned cat_descriptor pointer is not valid once the
       catclose() function has been called for that  cat_descriptor.

RETURN VALUES    [Toc]    [Back]

       On successful completion, the catgets() function returns a
       pointer to the null terminated  message  string  retrieved
       from  the  catalog.  Otherwise,  the  function  returns  a
       pointer to string and sets errno to indicate the error.

ERRORS    [Toc]    [Back]

       If the catgets() function fails, it sets errno to  one  of
       the  following  values  for  the  reason specified: [Tru64
       UNIX]  Search permission is denied for a component of  the
       path  to  the message catalog or read permission is denied
       for the catalog.

              [Tru64 UNIX]  This error may  occur  on  the  first
              invocation  of  catgets().  See catopen(3) for more
              information.  The  cat_descriptor  value  does  not
              identify   a  message  catalog  that  is  open  for
              reading.  The cat_descriptor argument is corrupted.
              [Tru64  UNIX]  The  process  limit  for  open  file
              descriptors  per  process   has   already   reached
              OPEN_MAX.

              [Tru64  UNIX]  This  error  may  occur on the first
              invocation of catgets(). See  catopen(3)  for  more
              information.   [Tru64  UNIX]  The  system limit for
              open file descriptors  has  been  reached.   [Tru64
              UNIX]  The message catalog does not exist.

              [Tru64  UNIX]  This  error  may  occur on the first
              invocation of catgets(). See  catopen(3)  for  more
              information.   [Tru64 UNIX]  Insufficient memory is
              available.

              [Tru64 UNIX]  This error may  occur  on  the  first
              invocation  of  catgets().  See catopen(3) for more
              information.  The message identified by  set_number
              and message_number is not in the catalog.

SEE ALSO    [Toc]    [Back]

       Functions: catopen(3), catclose(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



                                                       catgets(3)