gettext man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

GETTEXT(3C)							   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 category);

   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 *codeset);

       extern int _nl_msg_cat_cntr;
       extern int *_nl_domain_bindings;

       #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
       retrieve 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 get‐
       text() 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
       locale name, and category is either  LC_MESSAGES	 if  gettext(),	 dget‐
       text(),	ngettext(), or dngettext() is called, or LC_XXX where the name
       is the same as the locale category name specified by the category argu‐
       ment 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
       domain 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, names‐
       pace  collisions	 can be avoided by using  bindtextdomain(). If textdo‐
       main() is not called, a default domain  is  selected.  The  setting  of
       domain 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
       selected 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.

       The  external  variables	 _nl_msg_cat_cntr  and _nl_domain_bindings are
       provided for the compatibility with the GNU gettext() implementation.

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
       returned 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
       domainname is limited to TEXTDOMAINMAX (256) bytes.

       The   gettext(),	  dgettext(),  dcgettext(),  ngettext(),  dngettext(),
       dcngettext(), 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.m o

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

       /usr/lib/locale/locale/LC_XXX/domainname.mofR

	   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	   │
       ├────────────────────┼──────────────────────┤
       │Interface Stability │ See below.	   │
       ├────────────────────┼──────────────────────┤
       │MT-Level	    │ Safe with exceptions │
       └────────────────────┴──────────────────────┘

       The external variables  _nl_msg_cat_cntr	 and  _nl_domain_bindings  are
       Uncommitted.

SEE ALSO
       msgfmt(1),   xgettext(1),   iconv_open(3C),   libintl.h(3HEAD),	setlo‐
       cale(3C), attributes(5), environ(5)

				  Jun 4, 2008			   GETTEXT(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net