'\"macro stdmacro
.if n .pH g3c.gettxt @(#)gettxt	40.11 of 10/26/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} gettxt 3C "C Program Language Utilities"
.if \nX=1 .ds x} gettxt 3C "C Program Language Utilities"
.if \nX=2 .ds x} gettxt 3C "" "\&"
.if \nX=3 .ds x} gettxt "" "" "\&"
.TH \*(x}
.SH NAME
\f4gettxt\f1 \- retrieve a text string
.SH SYNOPSIS
.nf
.PP
\f4#include <nl_types.h>
.PP
\f4char \(**gettxt (const char \(**msgid, const char \(**dflt_str);\f1
.SH DESCRIPTION
\f4gettxt\fP
retrieves a text string from a message file. The
arguments to the function are a
message identification
.IR msgid
and a default string 
.IR dflt_str
to be used if the retrieval fails.
.PP
The text strings are in files created by the \f4mkmsgs\fP utility
[see \f4mkmsgs\fP(1)]
and installed in directories in
\f4/usr/lib/locale/\f2<locale>\fP/LC_MESSAGES\f1.
.PP
The directory \f2<locale>\f1 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
\f4LC_MESSAGES\f1.
If 
\f4LC_MESSAGES\f1 is not set, the environment
variable \f4LANG\f1 will be used.
If \f4LANG\f1 is not set,
the files
containing the strings are in \f4/usr/lib/locale/C/LC_MESSAGES/\(**\f1.
.PP
The user can also change the language in which the messages
are displayed by invoking the \f4setlocale\f1
function with the appropriate arguments.
.PP
If
\f4gettxt\fP
fails to retrieve a message in a specific language
it will try to retrieve the same message in \s-1U.S.\s+1 English.
On failure, the processing depends on what the
second argument
.IR dflt_str\^
points to.
A pointer to the second argument is returned if
the second argument is not the null string.
If 
.IR dflt_str\^
points to the null string,
a pointer to the \s-1U.S.\s+1 English text string
\f4"Message not found!!\\n"\fP is returned.
.PP
The following depicts the acceptable syntax of \f2msgid\f1
for a call to \f4gettxt\fP.
.PP
.RS
\f2<msgid>\f4 = \f2<msgfilename>\f4:\f2<msgnumber>\f1
.RE
.PP
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
.SM ASCII
code for \f4/\fP (slash) and \f4:\fP (colon).
The names of message files must be the same as the
names of files created by \f4mkmsgs\fP and installed
in \f4/usr/lib/locale/\f2<locale>\fP/LC_MESSAGES/\(**\f1.
The numeric field indicates the sequence
number of the string in the file.
The strings are numbered from 
.IR 1\^
to 
.IR n\^
where
.IR n\^
is the number of strings in the file.
.PP
On failure to pass the correct \f4msgid\f1 or
a valid message number to 
\f4gettxt\fP
a pointer to the text string
\f4"Message not found!!\\n"\fP is returned.
.SH EXAMPLE
.RS
.nf
.ft 4
gettxt("UX:10", "hello world\\n")
gettxt("UX:10", "")
.ft 1
.fi
.RE
.PP
\f4UX\fP is the name of the file that contains the messages.
\f410\fP is the message number.
.SH FILES
.nf
\f4/usr/lib/locale/C/LC_MESSAGES/\(**\fP	contains  default message files created by 
						\f4mkmsgs\fP
.PP
\f4/usr/lib/locale/\f2locale\fP/LC_MESSAGES/\(**\f1	contains message files for different 
							languages created by \f4mkmsgs\fP
.fi
.SH SEE ALSO
\f4fmtmsg\fP(3C),
\f4setlocale\fP(3C),
\f4environ\fP(5).
.br
\f4exstr\fP(1),
\f4mkmsgs\fP(1),
\f4srchtxt\fP(1)
in the
.IR "User's Reference Manual" .
.Ee
