gettxt(S-osr5)

gettxt -- retrieve a text string

Syntax

cc ...-lc

#include <unistd.h>

char *gettxt (const char *msgid, const char *dflt_str);

Description

gettxt(S-osr5) retrieves a text string from a message file generated by the mkmsgs(CP) utility. The arguments to the function are a message identification msgid and a default string dflt_str to be used if the retrieval fails.

For gettxt( ) to retrieve text strings from a message database, the msgid argument must have the following structure:

[msgfilename]:msgnumber

msgfilename: indicates the message database that contains the localized version of the text string. It can be up to 225 characters long. You can use any character values except null and the ASCII codes ``/'' (slash) and ``:'' (colon). The syntax for msgfilename is

filename[@archivename]
If archivename is specified, then gettxt( ) accesses the message database in an archive directory. The environment variable NLSPATH specifies the pathname for the message database, substituting filename for %N and archivename for %A. (See the explanation of NLSPATH, below.)
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(S-osr5) using the categories LC_ALL or LC_MESSAGES), or if the message number is out of bounds, gettxt( ) tries to retrieve the message from the C locale. If this second retrieval fails, gettxt( ) uses dflt_str.

If msgfilename is omitted, gettxt( ) tries to retrieve the string from the default catalog specified by the last call to setcat(S-osr5).

If NLSPATH does not exist in the environment, or if a message catalog can not be opened in any of the paths specified by NLSPATH, then the following default paths are used:

: "/usr/lib/nls/msg/%L/%A/%N"
: "/usr/lib/nls/msg/%l_%t/%A/%N"
: "/usr/lib/nls/msg/%l/%A/%N"
: "/etc/nls/msg/%L/%A/%N"
: "/etc/nls/msg/%l_%t/%A/%N"
: "/etc/nls/msg/%l/%A/%N"

where

%L: is the value of the LC_MESSAGES category
%l: is the language component from the LC_MESSAGES category
%t: is the territory component from the LC_MESSAGES category
%A: is the optional archive component of the message catalog name
%N: is the file component of the message catalog name

If the optional archive component is not in the message catalog name, %A is omitted from the NLSPATH definition.

%L can be viewed as the language in which the text strings are written. It is specified by the LC_MESSAGES category of setlocale( ), which is C by default.

You can change the language of the messages by invoking setlocale( ) with appropriate arguments.

You can also specify a language by setting environment variables (but only if the calling program calls setlocale(LC_MESSAGES,"") or setlocale(LC_ALL,""). 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.

Caution

gettxt( ) overwrites the string buffer each time it is called. To preserve the data, applications must copy it.

Return values

gettxt( ) returns a pointer to the text string it retrieved.

Diagnostics

If gettxt( ) outputs

Message not found!!

it indicates that gettxt( ) cannot retrieve the text string because of one of the following conditions:

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

Examples

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");
   gettxt("test:10", "");
   setcat("test");
   gettxt(":10", "hello world");

Standards conformance

gettxt(S-osr5) is not part of any currently supported standard; it was developed by UNIX System Laboratories, Inc. and is maintained by The SCO Group.