'\" te
.\"  Copyright 1989 AT&T  All Rights Reserved  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GETTXT 1 "Dec 20, 1996"
.SH NAME
gettxt \- retrieve a text string from a message database
.SH SYNOPSIS
.LP
.nf
\fBgettxt\fR \fImsgfile\fR : \fImsgnum\fR [\fIdflt_msg\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBgettxt\fR retrieves a text string from a message file in the directory
\fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB \fR. The
directory name \fIlocale\fR corresponds to the language in which the text
strings are written; see \fBsetlocale\fR(3C).
.sp
.ne 2
.na
\fB\fImsgfile\fR \fR
.ad
.RS 13n
Name of the file in the directory
\fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB \fR to retrieve
\fImsgnum\fR from. The name of \fImsgfile\fR can be up to 14 characters in
length, but may not contain either \e0 (null) or the \fBASCII\fR code for
\fB/\fR (slash) or \fB:\fR (colon).
.RE

.sp
.ne 2
.na
\fB\fImsgnum\fR \fR
.ad
.RS 13n
Sequence number of the string to retrieve from \fImsgfile\fR. The strings in
\fImsgfile\fR are numbered sequentially from \fI1\fR to \fIn\fR, where \fIn\fR
is the number of strings in the file.
.RE

.sp
.ne 2
.na
\fB\fIdflt_msg\fR \fR
.ad
.RS 13n
Default string to be displayed if \fBgettxt\fR fails to retrieve \fImsgnum\fR
from \fImsgfile\fR. Nongraphic characters must be represented as alphabetic
escape sequences.
.RE

.sp
.LP
The text string to be retrieved is in the file \fImsgfile\fR, created by the
\fBmkmsgs\fR(1) utility and installed under the directory
\fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB   \fR. You
control which directory is searched by setting the environment variable
\fBLC_MESSAGES\fR. If \fBLC_MESSAGES\fR is not set, the environment variable
\fBLANG\fR will be used. If \fBLANG\fR is not set, the files containing the
strings are under the directory \fB/usr/lib/locale/C/\fR\fBLC_MESSAGES\fR\fB
\fR.
.sp
.LP
If \fBgettxt\fR fails to retrieve a message in the requested language, it will
try to retrieve the same message from
\fB/usr/lib/locale/C/\fR\fBLC_MESSAGES\fR\fB/ \fR\fImsgfile\fR. If this also
fails, and if \fIdflt_msg\fR is present and non-null, then it will display the
value of \fIdflt_msg\fR; if \fIdflt_msg\fR is not present or is null, then it
will display the string \fBMessage not found!!\fR.
.SH EXAMPLES
.LP
\fBExample 1 \fRThe environment variables \fBLANG\fR and \fBLC_MESSAGES\fR.
.sp
.LP
If the environment variables \fBLANG\fR or \fBLC_MESSAGES\fR have not been set
to other than their default values, the following example:

.sp
.in +2
.nf
\fBexample% gettxt UX:10 "hello world\en"\fR
.fi
.in -2
.sp

.sp
.LP
will try to retrieve the 10th message from
\fB/usr/lib/locale/C/UX/\fR\fImsgfile\fR. If the retrieval fails, the message
"hello world," followed by a newline, will be displayed.

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of \fBgettxt\fR: \fBLC_CTYPE\fR and
\fB\fR\fBLC_MESSAGES\fR\fB\&.   \fR
.sp
.ne 2
.na
\fB\fBLC_CTYPE\fR \fR
.ad
.RS 16n
Determines how \fBgettxt\fR handles characters. When \fBLC_CTYPE\fR is set to a
valid value, \fBgettxt\fR can display and handle text and filenames containing
valid characters for that locale. \fBgettxt\fR can display and handle Extended
Unix Code (EUC) characters where any individual character can be 1, 2, or 3
bytes wide. \fBgettxt\fR can also handle \fBEUC\fR characters of 1, 2, or more
column widths. In the "C" locale, only characters from ISO 8859-1 are valid.
.RE

.sp
.ne 2
.na
\fB\fBLC_MESSAGES\fR \fR
.ad
.RS 16n
Determines how diagnostic and informative messages are presented. This includes
the language and style of the messages, and the correct form of affirmative and
negative responses.  In the "C" locale, the messages are presented in the
default form found in the program itself (in most cases, U.S. English).
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/locale/C/\fR\fBLC_MESSAGES\fR\fB/*   \fR\fR
.ad
.sp .6
.RS 4n
default message files created by \fBmkmsgs\fR(1)
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB/*   \fR\fR
.ad
.sp .6
.RS 4n
message files for different languages created by \fBmkmsgs\fR(1)
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
CSI	Enabled
.TE

.SH SEE ALSO
.sp
.LP
.BR exstr (1),
.BR mkmsgs (1),
.BR srchtxt (1),
.BR gettxt (3C),
.BR setlocale (3C),
.BR attributes (7),
.BR environ (7)