gettxt(3C)        UNIX System V(C Program Language Utilities)        gettxt(3C)


NAME
      gettxt - retrieve a text string

SYNOPSIS
      #include <unistd.h>

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

DESCRIPTION
      gettxt retrieves a text string from a message file. The arguments to the
      function are a message identification 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>/LCMESSAGES.

      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 LCMESSAGES.  If
      LCMESSAGES 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/LCMESSAGES/*.

      The user can also change the language in which the messages are displayed
      by invoking the setlocale 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>/LCMESSAGES/*.  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.

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




10/89                                                                    Page 1

gettxt(3C)        UNIX System V(C Program Language Utilities)        gettxt(3C)


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

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

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

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

SEE ALSO
      fmtmsg(3C), setlocale(3C), environ(5).
      exstr(1), mkmsgs(1), srchtxt(1) in the User's Reference Manual.





































Page 2                                                                    10/89