Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GETTEXT(3)		   Library Functions Manual		    GETTEXT(3)

       gettext,	 textdomain  - retrieve	a message string, get and set text do-

       char *gettext(msgtag)
       char *msgtag;

       char *textdomain(domainname)
       char *domainname;

       gettext()  returns  a  pointer  to  a  null-terminated  string  (target
       string).	  msgtag  is  a	 string	 used at run-time to select the	target
       string from the current domain of the active  pool  of  messages.   The
       length  and  contents of	strings	returned by gettext() are undetermined
       until called at run-time.  The string returned by gettext()  cannot  be
       modified	 by the	caller,	but may	be overwritten by a subsequent call to
       gettext().  The LC_MESSAGES locale category setting determines the  lo-
       cale of strings that gettext() returns.

       The  calling  process  can  dynamically change the choice of locale for
       strings returned	by gettext() by	invoking  the  setlocale(3V)  function
       with  the  correct category and the required locale.  If	setlocale() is
       not called or is	called with an invalid value,  gettext()  defaults  to
       the  "C"	 locale.  The default name for the current domain is the empty

       gettext() first attempts	to resolve the target string from  the	active
       domain  and  locale of the message pool.	 The current locale and	domain
       are determined by the combination of both the LC_MESSAGES  category  of
       locale and the current domain setting.

       If  the	target	string cannot be found by using	the current locale and
       domain then msgtag and current domain are applied  to  the  implementa-
       tion-defined default locale (this default locale	could contain any lan-
       guage).	If the default locale does not also contain the	target	string
       then the	msgtag and current domain will be applied to the "C" locale of
       the message pool.  If the target	string still cannot be found then get-
       text() will return msgtag.

       Any  of	the  following	conditions  will result	in a message not being
       found in	the string archive:

	      o	 Non-existent archive selected after  setlocale()  or  textdo-
		 main()	was called.

	      o	 Non-existent  archive	in  the	"C" environment	if setlocale()
		 was not called.

	      o	 Non-existent or deleted entry in the archive.

       textdomain() sets the current domain to domainname.   Subsequent	 calls
       to gettext() refer to this domain.  If domainname is NULL, textdomain()
       returns the name	of the current domain without changing it.

       The setting of domain made by the last successful textdomain() call re-
       mains valid across any number of	subsequent calls to setlocale().

       gettext()  returns  a  pointer  to the null-terminated target string on
       success.	 On failure, gettext() returns msgtag.

       textdomain() returns a pointer to the name of the current  domain.   If
       the  domain has not been	set prior to this call,	textdomain() returns a
       pointer to an empty string.  textdomain() returns NULL if:

	      o	 domainname contains an	invalid	character.

	      o	 domainname is longer than LINE_MAX bytes in length.

	      o	 If, at	the time of the	call to	textdomain(), the  combination
		 of  current  locale and domainname creates a domain that does
		 not exist at run-time.	 Note: in this case  textdomain()  may
		 have  been  called  prior to a	successful setlocale(3V) call,
		 but textdomain() will always  check  against  current	locale

       The following produces `Hit Return\n' in	a locale that is invalid or is
       valid and contains the same target string as the	key:

	      printf( gettext( "Hit Return\n" );

       On a system whose default language is French, and whose process has the
       LC_MESSAGES category validly set, the following might print: `Bonjour':

	      setlocale( LC_MESSAGES, "" );
	      textdomain( "Morning" );
	      printf( gettext( "Welcome" );

       If  the	LC_MESSAGES category was invalidly set and the default (LC_DE-
       FAULT) is set to	English, the last  example  above  might  print	 `Good
       morning'.   If  the  default is not set or is also invalid, the example
       would print `Welcome'.

       setlocale(3V), installtxt(8)

				22 January 1990			    GETTEXT(3)


Want to link to this manual page? Use this URL:

home | help