gettxt(S)

Syntax

#include <unistd.h>

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

Description

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 is omitted, gettxt( ) tries to retrieve the string from the default catalog specified by the last call to setcat(S).

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"

%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

%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

Return values

Diagnostics

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

   gettxt("test:10", "hello world");
   gettxt("test:10", "");
   setcat("test");
   gettxt(":10", "hello world");

See also

Standards conformance