gettxt(3C)

NAME

     gettxt - retrieve a text string

SYNOPSIS

     #include <nl_types.h>

     char *gettxt(const char *msgid, const char *dflt_str);

DESCRIPTION

     The gettxt() function retrieves a text string from a message
     file.  The arguments to the function are a message identifi-
     cation msgid and a default string dflt_str to be used if the
     retrieval fails.

     The text strings are in files created by the mkmsgs  utility
     (see    mkmsgs(1))   and   installed   in   directories   in
     /usr/lib/locale/locale/LC_MESSAGES.

     The directory locale can be viewed as the language in  which
     the text strings are written. The user can request that mes-
     sages be displayed in a specific  language  by  setting  the
     environment  variable  LC_MESSAGES.  If   LC_MESSAGES is not
     set, the environment variable LANG will be used. If LANG  is
     not   set,   the   files   containing  the  strings  are  in
     /usr/lib/locale/C/LC_MESSAGES/*.

     The user can also change the language in which the  messages
     are  displayed  by  invoking the setlocale(3C) function with
     the appropriate arguments.

     If gettxt() fails  to  retrieve  a  message  in  a  specific
     language  it  will  try to retrieve the same message in U.S.
     English. On failure, the  processing  depends  on  what  the
     second  argument dflt_str points to. A pointer to the second
     argument is returned if the second argument is not the  null
     string. If  dflt_str points to the null string, a pointer to
     the U.S. English text  string  "Message  not  found!!\n"  is
     returned.

     The following depicts the acceptable syntax of msgid  for  a
     call to gettxt().

          <msgid> = <msgfilename>:<msgnumber>

     The first field is used to indicate the file  that  contains
     the text strings and must be limited to 14 characters. These
     characters must be selected from the set  of  all  character
     values  excluding \0 (null) and the ASCII code for / (slash)
     and : (colon). The names of message files must be  the  same
     as  the  names  of  files created by mkmsgs and installed in
     /usr/lib/locale/locale/LC_MESSAGES/*.  The   numeric   field
     indicates the sequence number of the string in the file. The
     strings are numbered from 1 to n where n is  the  number  of
     strings in the file.

RETURN VALUES

     Upon failure to pass either the correct  msgid  or  a  valid
     message  number  to   gettxt(), a pointer to the text string
     "Message not found!!\n" is returned.

USAGE

     It is recommended that gettext(3C) be used in place of  this
     function.

EXAMPLES

     Example 1: Example of gettxt() function.

     In the following example,

     gettxt("UX:10", "hello world\n")
     gettxt("UX:10", "")

     UX is the name of the file that contains the messages and 10
     is the message number.

FILES

     /usr/lib/locale/C/LC_MESSAGES/*
           contains  default message files created by mkmsgs

     /usr/lib/locale/locale/LC_MESSAGES/*
           contains message files for different languages created
           by mkmsgs

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe with exceptions        |
    |_____________________________|_____________________________|

SEE ALSO

     exstr(1), mkmsgs(1),  srchtxt(1),  gettext(3C),  fmtmsg(3C),
     setlocale(3C), attributes(5), environ(5)