gettxt(3C)							    gettxt(3C)

NAME    [Toc]    [Back]

     gettxt - retrieve a text string

SYNOPSIS    [Toc]    [Back]

     #include <unistd.h>

     char *gettxt (const char *msgid<b>, const char *dflt_str<b>);

DESCRIPTION    [Toc]    [Back]

     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<b>/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<b>]: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    [Toc]    [Back]

     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    [Toc]    [Back]

     The following files are created by	mkmsgs:
	 /usr/lib/locale/C/LC_MESSAGES/*	default	message	files
	 /usr/lib/locale/locale<b>/LC_MESSAGES/*	message	files for language
						specified by locale

SEE ALSO    [Toc]    [Back]

     exstr(1), gettxt(1), mkmsgs(1), srchtxt(1), lfmt(3C), pfmt(3C),
     setcat(3C), setlocale(3C),	environ(5)


									PPPPaaaaggggeeee 2222