| blob | bbdd452a5d7555418454ff38f7eaae16f5e59808 |
1 '\" te
2 .\" Copyright 1989 AT&T All Rights Reserved Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH GETTXT 1 "Dec 20, 1996"
7 .SH NAME
8 gettxt \- retrieve a text string from a message database
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBgettxt\fR \fImsgfile\fR : \fImsgnum\fR [\fIdflt_msg\fR]
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 \fBgettxt\fR retrieves a text string from a message file in the directory
19 \fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB \fR. The
20 directory name \fIlocale\fR corresponds to the language in which the text
21 strings are written; see \fBsetlocale\fR(3C).
22 .sp
23 .ne 2
24 .na
25 \fB\fImsgfile\fR \fR
26 .ad
27 .RS 13n
28 Name of the file in the directory
29 \fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB \fR to retrieve
30 \fImsgnum\fR from. The name of \fImsgfile\fR can be up to 14 characters in
31 length, but may not contain either \e0 (null) or the \fBASCII\fR code for
32 \fB/\fR (slash) or \fB:\fR (colon).
33 .RE
35 .sp
36 .ne 2
37 .na
38 \fB\fImsgnum\fR \fR
39 .ad
40 .RS 13n
41 Sequence number of the string to retrieve from \fImsgfile\fR. The strings in
42 \fImsgfile\fR are numbered sequentially from \fI1\fR to \fIn\fR, where \fIn\fR
43 is the number of strings in the file.
44 .RE
46 .sp
47 .ne 2
48 .na
49 \fB\fIdflt_msg\fR \fR
50 .ad
51 .RS 13n
52 Default string to be displayed if \fBgettxt\fR fails to retrieve \fImsgnum\fR
53 from \fImsgfile\fR. Nongraphic characters must be represented as alphabetic
54 escape sequences.
55 .RE
57 .sp
58 .LP
59 The text string to be retrieved is in the file \fImsgfile\fR, created by the
60 \fBmkmsgs\fR(1) utility and installed under the directory
61 \fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB \fR. You
62 control which directory is searched by setting the environment variable
63 \fBLC_MESSAGES\fR. If \fBLC_MESSAGES\fR is not set, the environment variable
64 \fBLANG\fR will be used. If \fBLANG\fR is not set, the files containing the
65 strings are under the directory \fB/usr/lib/locale/C/\fR\fBLC_MESSAGES\fR\fB
66 \fR.
67 .sp
68 .LP
69 If \fBgettxt\fR fails to retrieve a message in the requested language, it will
70 try to retrieve the same message from
71 \fB/usr/lib/locale/C/\fR\fBLC_MESSAGES\fR\fB/ \fR\fImsgfile\fR. If this also
72 fails, and if \fIdflt_msg\fR is present and non-null, then it will display the
73 value of \fIdflt_msg\fR; if \fIdflt_msg\fR is not present or is null, then it
74 will display the string \fBMessage not found!!\fR.
75 .SH EXAMPLES
76 .LP
77 \fBExample 1 \fRThe environment variables \fBLANG\fR and \fBLC_MESSAGES\fR.
78 .sp
79 .LP
80 If the environment variables \fBLANG\fR or \fBLC_MESSAGES\fR have not been set
81 to other than their default values, the following example:
83 .sp
84 .in +2
85 .nf
86 \fBexample% gettxt UX:10 "hello world\en"\fR
87 .fi
88 .in -2
89 .sp
91 .sp
92 .LP
93 will try to retrieve the 10th message from
94 \fB/usr/lib/locale/C/UX/\fR\fImsgfile\fR. If the retrieval fails, the message
95 "hello world," followed by a newline, will be displayed.
97 .SH ENVIRONMENT VARIABLES
98 .sp
99 .LP
100 See \fBenviron\fR(5) for descriptions of the following environment variables
101 that affect the execution of \fBgettxt\fR: \fBLC_CTYPE\fR and
102 \fB\fR\fBLC_MESSAGES\fR\fB\&. \fR
103 .sp
104 .ne 2
105 .na
106 \fB\fBLC_CTYPE\fR \fR
107 .ad
108 .RS 16n
109 Determines how \fBgettxt\fR handles characters. When \fBLC_CTYPE\fR is set to a
110 valid value, \fBgettxt\fR can display and handle text and filenames containing
111 valid characters for that locale. \fBgettxt\fR can display and handle Extended
112 Unix Code (EUC) characters where any individual character can be 1, 2, or 3
113 bytes wide. \fBgettxt\fR can also handle \fBEUC\fR characters of 1, 2, or more
114 column widths. In the "C" locale, only characters from ISO 8859-1 are valid.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fBLC_MESSAGES\fR \fR
121 .ad
122 .RS 16n
123 Determines how diagnostic and informative messages are presented. This includes
124 the language and style of the messages, and the correct form of affirmative and
125 negative responses. In the "C" locale, the messages are presented in the
126 default form found in the program itself (in most cases, U.S. English).
127 .RE
129 .SH FILES
130 .sp
131 .ne 2
132 .na
133 \fB\fB/usr/lib/locale/C/\fR\fBLC_MESSAGES\fR\fB/* \fR\fR
134 .ad
135 .sp .6
136 .RS 4n
137 default message files created by \fBmkmsgs\fR(1)
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB/* \fR\fR
144 .ad
145 .sp .6
146 .RS 4n
147 message files for different languages created by \fBmkmsgs\fR(1)
148 .RE
150 .SH ATTRIBUTES
151 .sp
152 .LP
153 See \fBattributes\fR(5) for descriptions of the following attributes:
154 .sp
156 .sp
157 .TS
158 box;
159 c | c
160 l | l .
161 ATTRIBUTE TYPE ATTRIBUTE VALUE
162 CSI Enabled
163 .TE
165 .SH SEE ALSO
166 .sp
167 .LP
168 \fBexstr\fR(1), \fBmkmsgs\fR(1), \fBsrchtxt\fR(1), \fBgettxt\fR(3C),
169 \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5)