gettxt(3C) SDK R4.11 gettxt(3C)
NAME
gettxt - retrieve a text string
SYNOPSIS
#include <unistd.h>
char *gettxt (const char *msgid, const char *dfltstr);
DESCRIPTION
gettxt retrieves a text string from a AT&T-style message file. The
arguments to the function are a message identification msgid and a
default string dfltstr 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/LCMESSAGES.
The directory locale can be viewed as the language in which the text
strings are written. This is specified by the LCMESSAGES 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(LCMESSAGES,"") or setlocale(LCALL,"") is made from the
calling program). The first of the following environment variables
with a nonempty value is used: LCALL, LCMESSAGES, 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).
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 LCALL or LCMESSAGES 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 dfltstr.
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 dfltstr was omitted
Files
The following files are created by mkmsgs:
/usr/lib/locale/C/LCMESSAGES/*
default message files
/usr/lib/locale/locale/LCMESSAGES/*
message files for language specified by locale
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|gettxt | Y N N |
+---------+-----------------------------+
gettxt should be called when the other threads in a process are not
changing the LCMESSAGES locale. See the setlocale(3C) and
setcat(3C) man pages for more information.
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")
Notes
gettxt overwrites the string buffer each time it is called.
Applications should copy the data to preserve it.
REFERENCES
exstr(1), gettxt(1), mkmsgs(1), srchtxt(1), reentrant(3), pfmt(3C),
setcat(3C), setlocale(3C), environ(5)
gencat(1), catopen(3C), catgets(3C) -- X/Open-style message
facilities,
Licensed material--property of copyright holder(s)