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

FreeBSD Manual Pages

  
 
  

home | help
gettext(3C)		 Standard C Library Functions		   gettext(3C)

NAME
       gettext,	 dgettext, dcgettext, ngettext,	dngettext, dcngettext, textdo-
       main, bindtextdomain, bind_textdomain_codeset - message handling	 func-
       tions

SYNOPSIS
   Solaris and GNU-compatible
       #include	<libintl.h>

       char *gettext(const char	*msgid);

       char *dgettext(const char *domainname, const char *msgid);

       char *textdomain(const char *domainname);

       char *bindtextdomain(const char *domainname, const char *dirname);

       #include	<libintl.h>
       #include	<locale.h>

       char  *dcgettext(const  char  *domainname, const	char *msgid, int cate-
       gory);

   GNU-compatible
       #include	<libintl.h>

       char *ngettext(const char *msgid1, const	char  *msgid2,	unsigned  long
       int n);

       char  *dngettext(const char *domainname,	const char *msgid1, const char
       *msgid2,	unsigned long int n);

       char *bind_textdomain_codeset(const char	*domainname, const char	*code-
       set);

       #include	<libintl.h>
       #include	<locale.h>

       char *dcngettext(const char *domainname,	const char *msgid1, const char
       *msgid2,	unsigned long int n, int category);

DESCRIPTION
       The gettext(), dgettext(), and dcgettext()  functions  attempt  to  re-
       trieve a	target string based on the specified msgid argument within the
       context of a specific domain and	the  current  locale.  The  length  of
       strings returned	by gettext(),  dgettext(), and dcgettext() is undeter-
       mined until the function	is called. The msgid argument is a null-termi-
       nated string.

       The  ngettext(),	dngettext(), and dcngettext() functions	are equivalent
       to gettext(), dgettext(), and dcgettext(), respectively,	except for the
       handling	 of plural forms.  These functions work	only with GNU-compati-
       ble message catalogues.	The ngettext(),	dngettext(), and  dcngettext()
       functions  search  for  the message string using	the msgid1 argument as
       the key and the n argument to determine the plural form.	 If no message
       catalogues are found, msgid1 is returned	if n ==	1, otherwise msgid2 is
       returned.

       The NLSPATH environment variable	(see environ(5)) is searched first for
       the  location of	the  LC_MESSAGES catalogue. The	setting	of the LC_MES-
       SAGES category of the current locale  determines	 the  locale  used  by
       gettext()  and  dgettext()  for string retrieval. The category argument
       determines the locale used by dcgettext(). If NLSPATH  is  not  defined
       and  the	 current locale	is "C",	gettext(), dgettext(), and dcgettext()
       simply return the message string	that was passed.  In a	locale	 other
       than  "C",  if  NLSPATH is not defined or if a message catalogue	is not
       found in	any of the  components	specified  by  NLSPATH,	 the  routines
       search for the message catalogue	using the scheme described in the fol-
       lowing paragraph.

       The LANGUAGE environment	variable is examined to	determine the GNU-com-
       patible	message	catalogues to be used. The value of LANGUAGE is	a list
       of locale names separated by a colon (':') character.  If  LANGUAGE  is
       defined,	each locale name is tried in the specified order and if	a GNU-
       compatible message catalogue is found, the message is returned.	 If  a
       GNU-compatible  message	catalogue is found but failed to find a	corre-
       sponding	msgid, the msgid string	is return. If LANGUAGE is not  defined
       or if a Solaris message catalogue is found or no	GNU-compatible message
       catalogue is found in processing	LANGUAGE, the pathname used to	locate
       the  message  catalogue is dirname/locale/category/domainname.mo, where
       dirname is the directory	specified by bindtextdomain(), locale is a lo-
       cale name, and category is either LC_MESSAGES if	gettext(), dgettext(),
       ngettext(), or dngettext() is called, or	LC_XXX where the name  is  the
       same  as	the locale category name specified by the category argument to
       dcgettext() or dcngettext().

       For gettext() and ngettext(), the domain	used is	set by the last	 valid
       call  to	 textdomain().	If  a  valid call to textdomain() has not been
       made, the default domain	 (called messages) is used.

       For dgettext(), dcgettext(), dngettext(), and dcngettext(), the	domain
       used  is	 specified by the domainname argument. The domainname argument
       is equivalent in	syntax and  meaning  to	 the  domainname  argument  to
       textdomain(), except that the selection of the domain is	valid only for
       the duration of the dgettext(), dcgettext(),  dngettext(),  or  dcnget-
       text() function call.

       The  textdomain()  function sets	or queries the name of the current do-
       main of the active  LC_MESSAGES locale category.	The  domainname	 argu-
       ment  is	 a null-terminated string that can contain only	the characters
       allowed in legal	filenames.

       The domainname argument is the unique name of a domain on  the  system.
       If  there are multiple versions of the same domain on one system, name-
       space collisions	can be avoided by using	 bindtextdomain(). If  textdo-
       main()  is not called, a	default	domain is selected. The	setting	of do-
       main made by the	last valid call	to textdomain()	remains	 valid	across
       subsequent calls	to  setlocale(3C), and gettext().

       The  domainname argument	is applied to the currently active LC_MESSAGES
       locale.

       The current setting of the domain can be	queried	without	affecting  the
       current state of	the domain by calling textdomain() with	domainname set
       to the null pointer. Calling textdomain() with a	  domainname  argument
       of a null string	sets the domain	to the default domain (messages).

       The  bindtextdomain()  function	binds the path predicate for a message
       domain domainname to the	value contained	in dirname. If domainname is a
       non-empty  string  and  has not been bound previously, bindtextdomain()
       binds  domainname with  dirname.

       If  domainname is a non-empty string and	 has  been  bound  previously,
       bindtextdomain()	 replaces  the	old binding with  dirname. The dirname
       argument	can be an absolute or relative pathname	 being	resolved  when
       gettext(),  dgettext(),	or dcgettext() are called. If  domainname is a
       null pointer or an empty	string,	 bindtextdomain() returns  NULL.  User
       defined	domain	names  cannot begin with the string SYS_. Domain names
       beginning with this string are reserved for system use.

       The bind_textdomain_codeset() function can be used to specify the  out-
       put  codeset for	message	catalogues for domain domainname.  The codeset
       argument	must be	a  valid  codeset  name	 that  can  be	used  for  the
       iconv_open(3C)  function, or a null pointer. If the codeset argument is
       the null	pointer, bind_textdomain_codeset() returns the	currently  se-
       lected  codeset	for the	domain with the	name domainname.  It returns a
       null pointer if a codeset has not yet been selected.  The  bind_textdo-
       main_codeset()  function	 can be	used multiple times.  If used multiple
       times with the same domainname argument,	the later call	overrides  the
       settings	 made  by the earlier one. The bind_textdomain_codeset() func-
       tion returns a pointer to a string containing the name of the  selected
       codeset.	 The  string  is allocated internally in the function and must
       not be changed by the user.

RETURN VALUES
       The gettext(), dgettext(), and dcgettext() functions return the message
       string if the search succeeds. Otherwise	they return the	msgid string.

       The ngettext(), dngettext(), and	dcngettext() functions return the mes-
       sage string if the search succeeds.  If the search fails, msgid1	is re-
       turned if n == 1. Otherwise msgid2 is returned.

       The  individual bytes of	the string returned by gettext(),  dgettext(),
       dcgettext(), ngettext(),	dngettext(), or	dcngettext() can  contain  any
       value  other than NULL. If msgid	is a null pointer, the return value is
       undefined. The string returned must not be modified by the program  and
       can be invalidated by a subsequent call to bind_textdomain_codeset() or
       setlocale(3C). If the  domainname argument to   dgettext(),dcgettext(),
       dngettext(),  or	 dcngettext()  is  a null pointer, the the domain cur-
       rently bound by textdomain() is used.

       The normal return value from textdomain() is a pointer to a string con-
       taining	the  current  setting  of  the domain. If domainname is	a null
       pointer,	textdomain() returns a pointer to the  string  containing  the
       current	domain.	 If textdomain() was not previously called and domain-
       name is a null string, the name of the default domain is	returned.  The
       name  of	 the default domain is messages. If textdomain() fails,	a null
       pointer is returned.

       The return value	from bindtextdomain() is a null-terminated string con-
       taining	dirname	or the directory binding associated with domainname if
       dirname is NULL.	If no binding is found,	the default  return  value  is
       /usr/lib/locale.	 If   domainname is a null pointer or an empty string,
       bindtextdomain()	takes no action	and returns a null pointer. The	string
       returned	must not be modified by	the caller. If bindtextdomain()	fails,
       a null pointer is returned.

USAGE
       These functions impose no limit on message length. However, a text  do-
       mainname	is limited to TEXTDOMAINMAX (256) bytes.

       The  gettext(),	dgettext(),  dcgettext(), ngettext(), dngettext(), dc-
       ngettext(), textdomain(), and bindtextdomain() functions	 can  be  used
       safely  in  multithreaded applications, as long as setlocale(3C)	is not
       being called to change the locale.

       The gettext(), dgettext(), dcgettext(), textdomain(),  and  bindtextdo-
       main() functions	work with both Solaris message catalogues and GNU-com-
       patible message catalogues.  The	ngettext(), dngettext(), dcngettext(),
       and  bind_textdomain_codeset()  functions work only with	GNU-compatible
       message catalogues.  See	msgfmt(1) for information about	 Solaris  mes-
       sage catalogues and GNU-compatible message catalogues.

FILES
       /usr/lib/locale

	   default path	predicate for message domain files

       /usr/lib/locale/locale/LC_MESSAGES/domainname.mo

	   system  default location for	file containing	messages for  language
	   locale and domainname

       /usr/lib/locale/locale/LC_XXX/domainname.mo

	   system default location for file containing messages	for   language
	   locale  and	domainname  for	 dcgettext()  calls  where  LC_XXX  is
	   LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, or  LC_MES-
	   SAGES

       dirname/locale/LC_MESSAGES/domainname.mo

	   location  for  file	containing  messages for domain	domainname and
	   path	predicate dirname after	a successful call to bindtextdomain()

       dirname/locale/LC_XXX/domainname.mo

	   location for	files containing messages for domain domainname,  lan-
	   guage locale, and path predicate dirname after a successful call to
	   bindtextdomain() for	dcgettext()  calls  where  LC_XXX  is  one  of
	   LC_CTYPE,  LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, or LC_MES-
	   SAGES

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |Safe with	exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO
       msgfmt(1), xgettext(1), iconv_open(3C),	setlocale(3C),	attributes(5),
       environ(5)

SunOS 5.10			  1 May	2002			   gettext(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | FILES | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gettext&sektion=3c&manpath=SunOS+5.10>

home | help