gettxt(3C) (MLX Addendum)          (MLX)          gettxt(3C) (MLX Addendum)

NAME
     gettxt - retrieve a text string (MLX addendum)

SYNOPSIS
     char *gettxt(char *msgid, char *dfltstr);

DESCRIPTION
     The routine gettxt() retrieves a text string from a message file. The
     arguments to the function are a message identification msgid and a
     default string dfltstr to be used if the retrieval fails.

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

     The directory locale can be viewed as the language in which the text
     strings are written. The user can request that messages 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 locale in which the strings will be retrieved
     is the C locale and the files containing the strings are in
          /usr/lib/locale/C/LC_MESSAGES/*.

     An application can also change the language in which the messages are
     displayed by invoking the setlocale() [see setlocale(3C)] function
     with the appropriate arguments.

     If gettxt() fails to access the message in a specific locale, it will
     try to retrieve the same message in the C locale. Upon failure, the
     processing depends on what the second argument, dfltstr, points to. A
     pointer to the second argument is returned if the second argument is
     not the null string. If dfltstr points to the null string, a pointer
     to the C locale text string
          "Message not found!!\n"
     is returned. A pointer to the same string is also returned if the mes-
     sage number is out of range. Note that this string is always in
     English, exactly as shown here.

     The following depicts the acceptable syntax of msgid for a call to
     gettxt():
          <msgid> => <msgfilename>:<msgnumber>

     The first argument consists of two fields separated by a colon. 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 a 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/LCMESSAGES/*. If no file name is



Page 1                       Reliant UNIX 5.44                       6, 198

gettxt(3C) (MLX Addendum)          (MLX)          gettxt(3C) (MLX Addendum)

     specified, gettxt() will use the name specified with setcat(). If nei-
     ther a file name nor a default catalog is specified, gettxt() returns
     a pointer to the text string
          "Message not found!!\n".
     The numeric field indicates the sequence number of the string in the
     file. The strings are numbered from 1. If the numeric field is greater
     than the number of strings in the file, gettxt() will use defaults as
     described above.

     Upon failure to pass the correct argument to gettxt(), a pointer to
     the text string
          "Message not found!!\n"
     is returned.

FILES
     /usr/lib/locale/C/LC_MESSAGES/*              Default message files
                                                  created by mkmsgs()

     /usr/lib/locale/locale/LCMESSAGES/*         message files for dif-
                                                  ferent languages created
                                                  by mkmsgs()

EXAMPLE
     In the following code fragment:
          gettxt("test:10", "hello world\n")
          gettxt("test:10", "")
          setcat("test");
          gettxt(":10", "hello world\n")
     test is the name of the file that contains the messages; 10 is the
     message number.

SEE ALSO
     gettxt(1), mkmsgs(1), srchtxt(1), setcat(3C), setlocale(3C),
     environ(5).




















Page 2                       Reliant UNIX 5.44                       6, 198