gettxt(3C) gettxt(3C)
NAME
gettxt - retrieve a text string
SYNOPSIS
#include <unistd.h>
char *gettxt (const char *msgid, const char *dflt_str);
DESCRIPTION
gettxt 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. This is specified by the
LC_MESSAGES category of setlocale [see setlocale(3C)], which
is C by default.
The user can change the language in which the messages are
displayed by invoking the setlocale function with the
appropriate arguments.
The user can also request that messages be displayed in a
specific language by setting environment variables (but only
if a call to setlocale(LC_MESSAGES,"") or setlocale(LC_ALL,"")
is made from the calling program). The first of the following
environment variables with a nonempty value is used: LC_ALL,
LC_MESSAGES, and LANG.
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).
Copyright 1994 Novell, Inc. Page 1
gettxt(3C) gettxt(3C)
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).
gettxt outputs:
Message not found!!
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
Files
The following files are created by mkmsgs:
/usr/lib/locale/C/LC_MESSAGES/*
default message files
/usr/lib/locale/locale/LC_MESSAGES/*
message files for language specified by locale
USAGE
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");
Copyright 1994 Novell, Inc. Page 2
gettxt(3C) gettxt(3C)
Notes
gettxt overwrites the string buffer each time it is called.
Applications should copy the data to preserve it.
REFERENCES
environ(5), exstr(1), gettxt(1), mkmsgs(1), pfmt(3C),
setcat(3C), setlocale(3C), srchtxt(1)
Copyright 1994 Novell, Inc. Page 3