'\"macro stdmacro
.if n .pH g1.gettxt @(#)gettxt	40.13 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} gettxt 1 "Essential Utilities"
.if \nX=1 .ds x} gettxt 1 "Essential Utilities"
.if \nX=2 .ds x} gettxt 1 "" "\&"
.if \nX=3 .ds x} gettxt "" "" "\&"
.TH \*(x}
.SH NAME
\f4gettxt\f1 \- retrieve a text string from a message data base
.SH SYNOPSIS
\f4gettxt\f1
\f2msgfile\f4:\f2msgnum\f4 [\f2dflt_msg\f4]\f1
.SH DESCRIPTION
\f4gettxt\fP
retrieves a text string from a message file in the directory
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES\f1.
The directory name
.I locale
corresponds to the language in which the text strings are written;
see
\f4setlocale\fP(3C).
.PP
.TP 10
.I msgfile
Name of the file in the directory
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES\f1
to retrieve
.I msgnum
from.
The name of
.I msgfile
can be up to 14 characters in length,
but may not contain either \\0 (null)
or the
.SM 
ASCII
code for
\f4/\f1
(slash) or
\f4:\f1
(colon).
.TP 10
.I msgnum
Sequence number of the string to retrieve from
.IR msgfile .
The strings in
.I msgfile
are numbered sequentially from
.IR 1\^
to 
.IR n\^ ,
where
.IR n\^
is the number of strings in the file.
.TP 10
.I dflt_msg
Default string to be displayed if
\f4gettxt\f1 fails to retrieve
.I msgnum
from
.IR msgfile .
Nongraphic characters must be represented
as alphabetic escape sequences.
.PP
The text string to be retrieved is in the file
.IR msgfile ,
created by the
\f4mkmsgs\fP(1)
utility and installed under the directory
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES\f1.
You control which directory is searched 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
under the directory
\f4/usr/lib/locale/C/LC_MESSAGES\f1.
.PP
If
\f4gettxt\fP
fails to retrieve a message in the requested language,
it will try to retrieve the same message from 
\f4/usr/lib/locale/C/LC_MESSAGES/\f2msgfile\f1.
If this also fails, and if
.I dflt_msg
is present and non-null,
then it will display the value of
.IR dflt_msg ;
if
.I dflt_msg
is not present or is null, then
it will display the string
\f4Message not found!!\f1.
.SH EXAMPLE
If the environment variables
\f4LANG\f1
or
\f4LC_MESSAGES\f1
have not been set to
other than their default values,
.sp .5
.RS
\f4gettxt UX:10 "hello world\en"\fP
.RE
.sp .5
will try to retrieve the 10th message from
\f4/usr/lib/locale/C/UX/\f2msgfile\f1.
If the retrieval fails,
the message
"hello world,"
followed by a new-line, will be displayed.
.SK
.SH FILES
.PD 0
.TP 40
\f4/usr/lib/locale/C/LC_MESSAGES/\(**\f1
default message files created by \f4mkmsgs\fP(1)
.TP 40
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES/\(**\f1
message files for different languages created by \f4mkmsgs\fP(1)
.PD
.SH SEE ALSO
\f4exstr\fP(1),
\f4mkmsgs\fP(1),
\f4srchtxt\fP(1).
.br
\f4gettxt\fP(3C), \f4setlocale\fP(3C) in the
.IR "Programmer's Reference Manual" .
.Ee
