gettxt(3C)                                                       gettxt(3C)

NAME
     gettxt - retrieve text string from a message file

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
     dfltstr to be used if the retrieval fails.

     The text strings are in files created by the mkmsgs utility [see
     mkmsgs(1)] and are held 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 pro-
     cessing 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 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 num-
     bered 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.



Page 1                       Reliant UNIX 5.44                Printed 11/98

gettxt(3C)                                                       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 mes-
     sage 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
     exstr(1), mkmsgs(1), srchtxt(1), fmtmsg(3C), setlocale(3C),
     environ(5).





































Page 2                       Reliant UNIX 5.44                Printed 11/98