gettxt(3C)gettxt(3C)NAMEgettxt - retrieve a text string
SYNOPSIS
#include <unistd.h>
char *gettxt (const char *msgid, const char *dflt_str);
DESCRIPTIONgettxt retrieves a text string from a message file. The arguments to the
function are a message identification msgid and a default string dflt_str
to be used if the retrieval fails.
The text strings are in files created by the mkmsgs utility [see
mkmsgs(1)] and installed in directories in
/usr/lib/locale/locale/LC_MESSAGES.
The directory locale 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 environment variables. That is, the
locale directory searched is specified by the LC_MESSAGES environment
variable if it is set to a non-empty value. Otherwise, it is specified
by the LANG environment variable if it is set to a non-empty value.
Otherwise, the directory C is used.
The user can also change the language in which the messages are displayed
by invoking the setlocale function with the appropriate arguments. If
the locale is explicitly changed (via setlocale), the pointers returned
by gettxt may no longer be valid.
The following depicts the acceptable syntax of msgid for a call to
gettxt.
[msgfilename]:msgnumber
msgfilename indicates the message database that contains the localized
version of the text string. msgfilename must be limited to 14
characters. These characters must be selected from a set of all
characters values, excluding \0 (null) and the ASCII codes for / (slash)
and : (colon).
msgnum must be a positive number that indicates the index of the string
in the message database.
If msgfilename does not exist in the locale (specified by the last call
to setlocale using the LC_ALL or LC_MESSAGES categories), or if the
message number is out of bounds, gettxt attempts to retrieve the message
from the C locale. If this second retrieval fails, gettxt uses dflt_str.
If msgfilename is omitted, gettxt attempts to retrieve the string from
the default catalog specified by the last call to setcat(3C).
Page 1
gettxt(3C)gettxt(3C)gettxt outputs Message not found!!\n if:
- msgfilename is not a valid catalog name as defined above
- no catalog is specified (either explicitly or via setcat)
- msgnumber is not a positive number
- no message could be retrieved and dflt_str was omitted
EXAMPLE
In the following code fragment, test is the name of the file that
contains the messages and 10 is the message number.
gettxt("test:10", "hello world\n")
gettxt("test:10", "")
setcat("test");
gettxt(":10", "hello world\n")
FILES
The following files are created by mkmsgs:
default message files
/usr/lib/locale/C/LC_MESSAGES/*
message files for language
specified by locale
/usr/lib/locale/locale/LC_MESSAGES/*
SEE ALSOexstr(1), gettxt(1), mkmsgs(1), srchtxt(1), lfmt(3C), pfmt(3C),
setcat(3C), setlocale(3C), environ(5)
Page 2
