usr/src/man/man3c/gettxt.3c

   1 '\" te
   2 .\"  Copyright 1989 AT&T  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 3C "Dec 29, 1996"
   7 .SH NAME
   8 gettxt \- retrieve a text string
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <nl_types.h>
  13
  14 \fBchar *\fR\fBgettxt\fR(\fBconst char *\fR\fImsgid\fR, \fBconst char *\fR\fIdflt_str\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBgettxt()\fR function retrieves a text string from a message file. The
  21 arguments to the function are a message identification \fImsgid\fR and a
  22 default string \fIdflt_str\fR to be used if the retrieval fails.
  23 .sp
  24 .LP
  25 The text strings are in files created by the \fBmkmsgs\fR utility (see
  26 \fBmkmsgs\fR(1)) and installed in directories in
  27 \fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES\fR.
  28 .sp
  29 .LP
  30 The directory \fBlocale\fR can be viewed as the language in which the text
  31 strings are written. The user can request that messages be displayed in a
  32 specific language by setting the environment variable \fBLC_MESSAGES\fR. If
  33 \fBLC_MESSAGES\fR is not set, the environment variable \fBLANG\fR will be used.
  34 If \fBLANG\fR is not set, the files containing the strings are in
  35 \fB/usr/lib/locale/C/LC_MESSAGES/*\fR.
  36 .sp
  37 .LP
  38 The user can also change the language in which the messages are displayed by
  39 invoking the \fBsetlocale\fR(3C) function with the appropriate arguments.
  40 .sp
  41 .LP
  42 If \fBgettxt()\fR fails to retrieve a message in a specific language it will
  43 try to retrieve the same message in U.S. English. On failure, the processing
  44 depends on what the second argument \fIdflt_str\fR points to. A pointer to the
  45 second argument is returned if the second argument is not the null string. If
  46 \fIdflt_str\fR points to the null string, a pointer to the U.S. English text
  47 string \fB"Message not found!!\en"\fR is returned.
  48 .sp
  49 .LP
  50 The following depicts the acceptable syntax of \fImsgid\fR for a call to
  51 \fBgettxt()\fR.
  52 .sp
  53 .LP
  54 \fI<msgid>\fR\fB = \fR\fI<msgfilename>\fR\fB:\fR\fI<msgnumber>\fR
  55 .sp
  56 .LP
  57 The first field is used to indicate the file that contains the text strings and
  58 must be limited to 14 characters. These characters must be selected from the
  59 set of all character values excluding \e0 (null) and the \fBASCII\fR code for
  60 \fB/\fR (slash) and \fB:\fR (colon). The names of message files must be the
  61 same as the names of files created by \fBmkmsgs\fR and installed in
  62 \fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES/*\fR. The numeric field indicates
  63 the sequence number of the string in the file. The strings are numbered from 1
  64 to \fIn\fR where \fIn\fR is the number of strings in the file.
  65 .SH RETURN VALUES
  66 .sp
  67 .LP
  68 Upon failure to pass either the correct \fImsgid\fR or a valid message number
  69 to  \fBgettxt()\fR, a pointer to the text string \fB"Message not found!!\en"\fR
  70 is returned.
  71 .SH USAGE
  72 .sp
  73 .LP
  74 It is recommended that \fBgettext\fR(3C) be used in place of this function.
  75 .SH EXAMPLES
  76 .LP
  77 \fBExample 1 \fRExample of \fBgettxt()\fR function.
  78 .sp
  79 .LP
  80 In the following example,
  81
  82 .sp
  83 .in +2
  84 .nf
  85 gettxt("UX:10", "hello world\en")
  86 gettxt("UX:10", "")
  87 .fi
  88 .in -2
  89
  90 .sp
  91 .LP
  92 \fBUX\fR is the name of the file that contains the messages and \fB10\fR is the
  93 message number.
  94
  95 .SH FILES
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fB/usr/lib/locale/C/LC_MESSAGES/*\fR\fR
 100 .ad
 101 .sp .6
 102 .RS 4n
 103 contains  default message files created by \fBmkmsgs\fR
 104 .RE
 105
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fB/usr/lib/locale/\fIlocale\fR/LC_MESSAGES/*\fR\fR
 110 .ad
 111 .sp .6
 112 .RS 4n
 113 contains message files for different languages created by \fBmkmsgs\fR
 114 .RE
 115
 116 .SH ATTRIBUTES
 117 .sp
 118 .LP
 119 See \fBattributes\fR(5) for descriptions of the following attributes:
 120 .sp
 121
 122 .sp
 123 .TS
 124 box;
 125 c | c
 126 l | l .
 127 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 128 _
 129 MT-Level        Safe with exceptions
 130 .TE
 131
 132 .SH SEE ALSO
 133 .sp
 134 .LP
 135 \fBexstr\fR(1), \fBmkmsgs\fR(1), \fBsrchtxt\fR(1), \fBgettext\fR(3C),
 136 \fBfmtmsg\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5)